<!DOCTYPE html>
<html lang="en" data-content_root="../../../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Generic vcpu interface — The Linux Kernel documentation</title>
<link rel="stylesheet" type="text/css" href="../../../_static/pygments.css?v=fa44fd50" />
<link rel="stylesheet" type="text/css" href="../../../_static/alabaster.css?v=3918102e" />
<script src="../../../_static/documentation_options.js?v=5929fcd5"></script>
<script src="../../../_static/doctools.js?v=9bcbadda"></script>
<script src="../../../_static/sphinx_highlight.js?v=dc90522c"></script>
<link rel="index" title="Index" href="../../../genindex.html" />
<link rel="search" title="Search" href="../../../search.html" />
<link rel="next" title="VFIO virtual device" href="vfio.html" />
<link rel="prev" title="FLIC (floating interrupt controller)" href="s390_flic.html" />
<link rel="stylesheet" href="../../../_static/custom.css" type="text/css" />
</head><body>
<div class="document">
<div class="sphinxsidebar" role="navigation" aria-label="Main">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="../../../index.html">
<img class="logo" src="../../../_static/logo.svg" alt="Logo of The Linux Kernel"/>
</a></p>
<h1 class="logo"><a href="../../../index.html">The Linux Kernel</a></h1>
<p class="blurb">6.18.50</p>
<search id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../../../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</search>
<script>document.getElementById('searchbox').style.display = "block"</script>
<p>
<h3 class="kernel-toc-contents">Contents</h3>
<input type="checkbox" class="kernel-toc-toggle" id = "kernel-toc-toggle" checked>
<label class="kernel-toc-title" for="kernel-toc-toggle"></label>
<div class="kerneltoc" id="kerneltoc">
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../../process/development-process.html">Development process</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../process/submitting-patches.html">Submitting patches</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../process/code-of-conduct.html">Code of conduct</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../maintainer/index.html">Maintainer handbook</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../process/index.html">All development-process docs</a></li>
</ul>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../../../core-api/index.html">Core API</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../driver-api/index.html">Driver APIs</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../../../subsystem-apis.html">Subsystems</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../../../subsystem-apis.html#core-subsystems">Core subsystems</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../../subsystem-apis.html#human-interfaces">Human interfaces</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../../subsystem-apis.html#networking-interfaces">Networking interfaces</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../../subsystem-apis.html#storage-interfaces">Storage interfaces</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="../../../subsystem-apis.html#other-subsystems">Other subsystems</a><ul class="current">
<li class="toctree-l3"><a class="reference internal" href="../../../accounting/index.html">Accounting</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../../cpu-freq/index.html">CPUFreq - CPU frequency and voltage scaling code in the Linux(TM) kernel</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../../edac/index.html">EDAC Subsystem</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../../fpga/index.html">FPGA</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../../i2c/index.html">I2C/SMBus Subsystem</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../../iio/index.html">Industrial I/O</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../../pcmcia/index.html">PCMCIA</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../../spi/index.html">Serial Peripheral Interface (SPI)</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../../w1/index.html">1-Wire Subsystem</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../../watchdog/index.html">Watchdog Support</a></li>
<li class="toctree-l3 current"><a class="reference internal" href="../../index.html">Virtualization Support</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../../hwmon/index.html">Hardware Monitoring</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../../accel/index.html">Compute Accelerators</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../../security/index.html">Security Documentation</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../../crypto/index.html">Crypto API</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../../bpf/index.html">BPF Documentation</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../../usb/index.html">USB support</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../../PCI/index.html">PCI Bus Subsystem</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../../misc-devices/index.html">Assorted Miscellaneous Devices Documentation</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../../peci/index.html">PECI Subsystem</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../../wmi/index.html">WMI Subsystem</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../../tee/index.html">TEE Subsystem</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../../locking/index.html">Locking</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../../process/license-rules.html">Licensing rules</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../doc-guide/index.html">Writing documentation</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../dev-tools/index.html">Development tools</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../dev-tools/testing-overview.html">Testing guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../kernel-hacking/index.html">Hacking guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../trace/index.html">Tracing</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../fault-injection/index.html">Fault injection</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../livepatch/index.html">Livepatching</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../rust/index.html">Rust</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../../admin-guide/index.html">Administration</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../kbuild/index.html">Build system</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../admin-guide/reporting-issues.html">Reporting issues</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../tools/index.html">Userspace tools</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../userspace-api/index.html">Userspace API</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../../firmware-guide/index.html">Firmware</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../devicetree/index.html">Firmware and Devicetree</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../../arch/index.html">CPU architectures</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../../staging/index.html">Unsorted documentation</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../../translations/index.html">Translations</a></li>
</ul>
</div>
<script type="text/javascript"> <!--
var sbar = document.getElementsByClassName("sphinxsidebar")[0];
let currents = document.getElementsByClassName("current")
if (currents.length) {
sbar.scrollTop = currents[currents.length - 1].offsetTop;
}
--> </script>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../../../_sources/virt/kvm/devices/vcpu.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
</div>
</div>
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="generic-vcpu-interface">
<h1>Generic vcpu interface<a class="headerlink" href="#generic-vcpu-interface" title="Link to this heading">¶</a></h1>
<p>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 <code class="xref c c-struct broken_xref docutils literal notranslate"><span class="pre">struct</span>
<span class="pre">kvm_device_attr</span></code> as other devices, but targets VCPU-wide settings and controls.</p>
<p>The groups and attributes per virtual cpu, if any, are architecture specific.</p>
<section id="group-kvm-arm-vcpu-pmu-v3-ctrl">
<h2>1. GROUP: KVM_ARM_VCPU_PMU_V3_CTRL<a class="headerlink" href="#group-kvm-arm-vcpu-pmu-v3-ctrl" title="Link to this heading">¶</a></h2>
<dl class="field-list simple">
<dt class="field-odd">Architectures<span class="colon">:</span></dt>
<dd class="field-odd"><p>ARM64</p>
</dd>
</dl>
<section id="attribute-kvm-arm-vcpu-pmu-v3-irq">
<h3>1.1. ATTRIBUTE: KVM_ARM_VCPU_PMU_V3_IRQ<a class="headerlink" href="#attribute-kvm-arm-vcpu-pmu-v3-irq" title="Link to this heading">¶</a></h3>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p>in kvm_device_attr.addr the address for PMU overflow interrupt is a
pointer to an int</p>
</dd>
</dl>
<p>Returns:</p>
<blockquote>
<div><table class="docutils align-default">
<tbody>
<tr class="row-odd"><td><p>-EBUSY</p></td>
<td><p>The PMU overflow interrupt is already set</p></td>
</tr>
<tr class="row-even"><td><p>-EFAULT</p></td>
<td><p>Error reading interrupt number</p></td>
</tr>
<tr class="row-odd"><td><p>-ENXIO</p></td>
<td><p>PMUv3 not supported or the overflow interrupt not set
when attempting to get it</p></td>
</tr>
<tr class="row-even"><td><p>-ENODEV</p></td>
<td><p>KVM_ARM_VCPU_PMU_V3 feature missing from VCPU</p></td>
</tr>
<tr class="row-odd"><td><p>-EINVAL</p></td>
<td><p>Invalid PMU overflow interrupt number supplied or
trying to set the IRQ number without using an in-kernel
irqchip.</p></td>
</tr>
</tbody>
</table>
</div></blockquote>
<p>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.</p>
</section>
<section id="attribute-kvm-arm-vcpu-pmu-v3-init">
<h3>1.2 ATTRIBUTE: KVM_ARM_VCPU_PMU_V3_INIT<a class="headerlink" href="#attribute-kvm-arm-vcpu-pmu-v3-init" title="Link to this heading">¶</a></h3>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p>no additional parameter in kvm_device_attr.addr</p>
</dd>
</dl>
<p>Returns:</p>
<blockquote>
<div><table class="docutils align-default">
<tbody>
<tr class="row-odd"><td><p>-EEXIST</p></td>
<td><p>Interrupt number already used</p></td>
</tr>
<tr class="row-even"><td><p>-ENODEV</p></td>
<td><p>PMUv3 not supported or GIC not initialized</p></td>
</tr>
<tr class="row-odd"><td><p>-ENXIO</p></td>
<td><p>PMUv3 not supported, missing VCPU feature or interrupt
number not set</p></td>
</tr>
<tr class="row-even"><td><p>-EBUSY</p></td>
<td><p>PMUv3 already initialized</p></td>
</tr>
</tbody>
</table>
</div></blockquote>
<p>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.</p>
</section>
<section id="attribute-kvm-arm-vcpu-pmu-v3-filter">
<h3>1.3 ATTRIBUTE: KVM_ARM_VCPU_PMU_V3_FILTER<a class="headerlink" href="#attribute-kvm-arm-vcpu-pmu-v3-filter" title="Link to this heading">¶</a></h3>
<dl class="field-list">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p>in kvm_device_attr.addr the address for a PMU event filter is a
pointer to a <code class="xref c c-struct broken_xref docutils literal notranslate"><span class="pre">struct</span> <span class="pre">kvm_pmu_event_filter</span></code></p>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><table class="docutils align-default">
<tbody>
<tr class="row-odd"><td><p>-ENODEV</p></td>
<td><p>PMUv3 not supported or GIC not initialized</p></td>
</tr>
<tr class="row-even"><td><p>-ENXIO</p></td>
<td><p>PMUv3 not properly configured or in-kernel irqchip not
configured as required prior to calling this attribute</p></td>
</tr>
<tr class="row-odd"><td><p>-EBUSY</p></td>
<td><p>PMUv3 already initialized or a VCPU has already run</p></td>
</tr>
<tr class="row-even"><td><p>-EINVAL</p></td>
<td><p>Invalid filter range</p></td>
</tr>
</tbody>
</table>
</dd>
</dl>
<p>Request the installation of a PMU event filter described as follows:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>struct kvm_pmu_event_filter {
__u16 base_event;
__u16 nevents;
#define KVM_PMU_EVENT_ALLOW 0
#define KVM_PMU_EVENT_DENY 1
__u8 action;
__u8 pad[3];
};
</pre></div>
</div>
<p>A filter range is defined as the range [@base_event, @base_event + @nevents),
together with an @action (KVM_PMU_EVENT_ALLOW or KVM_PMU_EVENT_DENY). The
first registered range defines the global policy (global ALLOW if the first
@action is DENY, global DENY if the first @action is ALLOW). Multiple ranges
can be programmed, and must fit within the event space defined by the PMU
architecture (10 bits on ARMv8.0, 16 bits from ARMv8.1 onwards).</p>
<p>Note: “Cancelling” a filter by registering the opposite action for the same
range doesn’t change the default action. For example, installing an ALLOW
filter for event range [0:10) as the first filter and then applying a DENY
action for the same range will leave the whole range as disabled.</p>
<p>Restrictions: Event 0 (SW_INCR) is never filtered, as it doesn’t count a
hardware event. Filtering event 0x1E (CHAIN) has no effect either, as it
isn’t strictly speaking an event. Filtering the cycle counter is possible
using event 0x11 (CPU_CYCLES).</p>
</section>
<section id="attribute-kvm-arm-vcpu-pmu-v3-set-pmu">
<h3>1.4 ATTRIBUTE: KVM_ARM_VCPU_PMU_V3_SET_PMU<a class="headerlink" href="#attribute-kvm-arm-vcpu-pmu-v3-set-pmu" title="Link to this heading">¶</a></h3>
<dl class="field-list">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p>in kvm_device_attr.addr the address to an int representing the PMU
identifier.</p>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><table class="docutils align-default">
<tbody>
<tr class="row-odd"><td><p>-EBUSY</p></td>
<td><p>PMUv3 already initialized, a VCPU has already run or
an event filter has already been set</p></td>
</tr>
<tr class="row-even"><td><p>-EFAULT</p></td>
<td><p>Error accessing the PMU identifier</p></td>
</tr>
<tr class="row-odd"><td><p>-ENXIO</p></td>
<td><p>PMU not found</p></td>
</tr>
<tr class="row-even"><td><p>-ENODEV</p></td>
<td><p>PMUv3 not supported or GIC not initialized</p></td>
</tr>
<tr class="row-odd"><td><p>-ENOMEM</p></td>
<td><p>Could not allocate memory</p></td>
</tr>
</tbody>
</table>
</dd>
</dl>
<p>Request that the VCPU uses the specified hardware PMU when creating guest events
for the purpose of PMU emulation. The PMU identifier can be read from the “type”
file for the desired PMU instance under /sys/devices (or, equivalent,
/sys/bus/even_source). This attribute is particularly useful on heterogeneous
systems where there are at least two CPU PMUs on the system. The PMU that is set
for one VCPU will be used by all the other VCPUs. It isn’t possible to set a PMU
if a PMU event filter is already present.</p>
<p>Note that KVM will not make any attempts to run the VCPU on the physical CPUs
associated with the PMU specified by this attribute. This is entirely left to
userspace. However, attempting to run the VCPU on a physical CPU not supported
by the PMU will fail and KVM_RUN will return with
exit_reason = KVM_EXIT_FAIL_ENTRY and populate the fail_entry <code class="xref c c-struct broken_xref docutils literal notranslate"><span class="pre">struct</span> <span class="pre">by</span></code> setting
hardare_entry_failure_reason field to KVM_EXIT_FAIL_ENTRY_CPU_UNSUPPORTED and
the cpu field to the processor id.</p>
</section>
<section id="attribute-kvm-arm-vcpu-pmu-v3-set-nr-counters">
<h3>1.5 ATTRIBUTE: KVM_ARM_VCPU_PMU_V3_SET_NR_COUNTERS<a class="headerlink" href="#attribute-kvm-arm-vcpu-pmu-v3-set-nr-counters" title="Link to this heading">¶</a></h3>
<dl class="field-list">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p>in kvm_device_attr.addr the address to an unsigned int
representing the maximum value taken by PMCR_EL0.N</p>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><table class="docutils align-default">
<tbody>
<tr class="row-odd"><td><p>-EBUSY</p></td>
<td><p>PMUv3 already initialized, a VCPU has already run or
an event filter has already been set</p></td>
</tr>
<tr class="row-even"><td><p>-EFAULT</p></td>
<td><p>Error accessing the value pointed to by addr</p></td>
</tr>
<tr class="row-odd"><td><p>-ENODEV</p></td>
<td><p>PMUv3 not supported or GIC not initialized</p></td>
</tr>
<tr class="row-even"><td><p>-EINVAL</p></td>
<td><p>No PMUv3 explicitly selected, or value of N out of
range</p></td>
</tr>
</tbody>
</table>
</dd>
</dl>
<p>Set the number of implemented event counters in the virtual PMU. This
mandates that a PMU has explicitly been selected via
KVM_ARM_VCPU_PMU_V3_SET_PMU, and will fail when no PMU has been
explicitly selected, or the number of counters is out of range for the
selected PMU. Selecting a new PMU cancels the effect of setting this
attribute.</p>
</section>
</section>
<section id="group-kvm-arm-vcpu-timer-ctrl">
<h2>2. GROUP: KVM_ARM_VCPU_TIMER_CTRL<a class="headerlink" href="#group-kvm-arm-vcpu-timer-ctrl" title="Link to this heading">¶</a></h2>
<dl class="field-list simple">
<dt class="field-odd">Architectures<span class="colon">:</span></dt>
<dd class="field-odd"><p>ARM64</p>
</dd>
</dl>
<section id="attributes-kvm-arm-vcpu-timer-irq-vtimer-ptimer-hvtimer-hptimer">
<h3>2.1. ATTRIBUTES: KVM_ARM_VCPU_TIMER_IRQ_{VTIMER,PTIMER,HVTIMER,HPTIMER}<a class="headerlink" href="#attributes-kvm-arm-vcpu-timer-irq-vtimer-ptimer-hvtimer-hptimer" title="Link to this heading">¶</a></h3>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p>in kvm_device_attr.addr the address for the timer interrupt is a
pointer to an int</p>
</dd>
</dl>
<p>Returns:</p>
<blockquote>
<div><table class="docutils align-default">
<tbody>
<tr class="row-odd"><td><p>-EINVAL</p></td>
<td><p>Invalid timer interrupt number</p></td>
</tr>
<tr class="row-even"><td><p>-EBUSY</p></td>
<td><p>One or more VCPUs has already run</p></td>
</tr>
</tbody>
</table>
</div></blockquote>
<p>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).</p>
<table class="docutils align-default">
<tbody>
<tr class="row-odd"><td><p>KVM_ARM_VCPU_TIMER_IRQ_VTIMER</p></td>
<td><p>The EL1 virtual timer intid (default: 27)</p></td>
</tr>
<tr class="row-even"><td><p>KVM_ARM_VCPU_TIMER_IRQ_PTIMER</p></td>
<td><p>The EL1 physical timer intid (default: 30)</p></td>
</tr>
<tr class="row-odd"><td><p>KVM_ARM_VCPU_TIMER_IRQ_HVTIMER</p></td>
<td><p>The EL2 virtual timer intid (default: 28)</p></td>
</tr>
<tr class="row-even"><td><p>KVM_ARM_VCPU_TIMER_IRQ_HPTIMER</p></td>
<td><p>The EL2 physical timer intid (default: 26)</p></td>
</tr>
</tbody>
</table>
<p>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.</p>
</section>
</section>
<section id="group-kvm-arm-vcpu-pvtime-ctrl">
<span id="kvm-arm-vcpu-pvtime-ctrl"></span><h2>3. GROUP: KVM_ARM_VCPU_PVTIME_CTRL<a class="headerlink" href="#group-kvm-arm-vcpu-pvtime-ctrl" title="Link to this heading">¶</a></h2>
<dl class="field-list simple">
<dt class="field-odd">Architectures<span class="colon">:</span></dt>
<dd class="field-odd"><p>ARM64</p>
</dd>
</dl>
<section id="attribute-kvm-arm-vcpu-pvtime-ipa">
<h3>3.1 ATTRIBUTE: KVM_ARM_VCPU_PVTIME_IPA<a class="headerlink" href="#attribute-kvm-arm-vcpu-pvtime-ipa" title="Link to this heading">¶</a></h3>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p>64-bit base address</p>
</dd>
</dl>
<p>Returns:</p>
<blockquote>
<div><table class="docutils align-default">
<tbody>
<tr class="row-odd"><td><p>-ENXIO</p></td>
<td><p>Stolen time not implemented</p></td>
</tr>
<tr class="row-even"><td><p>-EEXIST</p></td>
<td><p>Base address already set for this VCPU</p></td>
</tr>
<tr class="row-odd"><td><p>-EINVAL</p></td>
<td><p>Base address not 64 byte aligned</p></td>
</tr>
</tbody>
</table>
</div></blockquote>
<p>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 <a class="reference internal" href="../arm/pvtime.html"><span class="doc">Paravirtualized time support for arm64</span></a> for more information
including the layout of the stolen time structure.</p>
</section>
</section>
<section id="group-kvm-vcpu-tsc-ctrl">
<h2>4. GROUP: KVM_VCPU_TSC_CTRL<a class="headerlink" href="#group-kvm-vcpu-tsc-ctrl" title="Link to this heading">¶</a></h2>
<dl class="field-list simple">
<dt class="field-odd">Architectures<span class="colon">:</span></dt>
<dd class="field-odd"><p>x86</p>
</dd>
</dl>
<p>4.1 ATTRIBUTE: KVM_VCPU_TSC_OFFSET</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p>64-bit unsigned TSC offset</p>
</dd>
</dl>
<p>Returns:</p>
<blockquote>
<div><table class="docutils align-default">
<tbody>
<tr class="row-odd"><td><p>-EFAULT</p></td>
<td><p>Error reading/writing the provided
parameter address.</p></td>
</tr>
<tr class="row-even"><td><p>-ENXIO</p></td>
<td><p>Attribute not supported</p></td>
</tr>
</tbody>
</table>
</div></blockquote>
<p>Specifies the guest’s TSC offset relative to the host’s TSC. The guest’s
TSC is then derived by the following equation:</p>
<blockquote>
<div><p>guest_tsc = host_tsc + KVM_VCPU_TSC_OFFSET</p>
</div></blockquote>
<p>This attribute is useful to adjust the guest’s TSC on live migration,
so that the TSC counts the time during which the VM was paused. The
following describes a possible algorithm to use for this purpose.</p>
<p>From the source VMM process:</p>
<ol class="arabic simple">
<li><p>Invoke the KVM_GET_CLOCK ioctl to record the host TSC (tsc_src),
kvmclock nanoseconds (guest_src), and host CLOCK_REALTIME nanoseconds
(host_src).</p></li>
<li><p>Read the KVM_VCPU_TSC_OFFSET attribute for every vCPU to record the
guest TSC offset (ofs_src[i]).</p></li>
<li><p>Invoke the KVM_GET_TSC_KHZ ioctl to record the frequency of the
guest’s TSC (freq).</p></li>
</ol>
<p>From the destination VMM process:</p>
<ol class="arabic" start="4">
<li><p>Invoke the KVM_SET_CLOCK ioctl, providing the source nanoseconds from
kvmclock (guest_src) and CLOCK_REALTIME (host_src) in their respective
fields. Ensure that the KVM_CLOCK_REALTIME flag is set in the provided
structure.</p>
<p>KVM will advance the VM’s kvmclock to account for elapsed time since
recording the clock values. Note that this will cause problems in
the guest (e.g., timeouts) unless CLOCK_REALTIME is synchronized
between the source and destination, and a reasonably short time passes
between the source pausing the VMs and the destination executing
steps 4-7.</p>
</li>
<li><p>Invoke the KVM_GET_CLOCK ioctl to record the host TSC (tsc_dest) and
kvmclock nanoseconds (guest_dest).</p></li>
<li><p>Adjust the guest TSC offsets for every vCPU to account for (1) time
elapsed since recording state and (2) difference in TSCs between the
source and destination machine:</p>
<dl class="simple">
<dt>ofs_dst[i] = ofs_src[i] -</dt><dd><p>(guest_src - guest_dest) * freq +
(tsc_src - tsc_dest)</p>
</dd>
</dl>
<p>(“ofs[i] + tsc - guest * freq” is the guest TSC value corresponding to
a time of 0 in kvmclock. The above formula ensures that it is the
same on the destination as it was on the source).</p>
</li>
<li><p>Write the KVM_VCPU_TSC_OFFSET attribute for every vCPU with the
respective value derived in the previous step.</p></li>
</ol>
</section>
</section>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
©The kernel development community.
|
Powered by <a href="https://www.sphinx-doc.org/">Sphinx 8.1.3</a>
& <a href="https://alabaster.readthedocs.io">Alabaster 0.7.16</a>
|
<a href="../../../_sources/virt/kvm/devices/vcpu.rst.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>