<!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>Linux KVM Hypercall — 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="Intel Trust Domain Extensions (TDX)" href="intel-tdx.html" />
<link rel="prev" title="Known limitations of CPU virtualization" href="errata.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/x86/hypercalls.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="linux-kvm-hypercall">
<h1>Linux KVM Hypercall<a class="headerlink" href="#linux-kvm-hypercall" title="Link to this heading">¶</a></h1>
<dl>
<dt>X86:</dt><dd><p>KVM Hypercalls have a three-byte sequence of either the vmcall or the vmmcall
instruction. The hypervisor can replace it with instructions that are
guaranteed to be supported.</p>
<p>Up to four arguments may be passed in rbx, rcx, rdx, and rsi respectively.
The hypercall number should be placed in rax and the return value will be
placed in rax. No other registers will be clobbered unless explicitly stated
by the particular hypercall.</p>
</dd>
<dt>S390:</dt><dd><p>R2-R7 are used for parameters 1-6. In addition, R1 is used for hypercall
number. The return value is written to R2.</p>
<p>S390 uses diagnose instruction as hypercall (0x500) along with hypercall
number in R1.</p>
<p>For further information on the S390 diagnose call as supported by KVM,
refer to <a class="reference internal" href="../s390/s390-diag.html"><span class="doc">The s390 DIAGNOSE call on KVM</span></a>.</p>
</dd>
<dt>PowerPC:</dt><dd><p>It uses R3-R10 and hypercall number in R11. R4-R11 are used as output registers.
Return value is placed in R3.</p>
<p>KVM hypercalls uses 4 byte opcode, that are patched with ‘hypercall-instructions’
property inside the device tree’s /hypervisor node.
For more information refer to <a class="reference internal" href="../ppc-pv.html"><span class="doc">The PPC KVM paravirtual interface</span></a></p>
</dd>
<dt>MIPS:</dt><dd><p>KVM hypercalls use the HYPCALL instruction with code 0 and the hypercall
number in $2 (v0). Up to four arguments may be placed in $4-$7 (a0-a3) and
the return value is placed in $2 (v0).</p>
</dd>
</dl>
<section id="kvm-hypercalls-documentation">
<h2>KVM Hypercalls Documentation<a class="headerlink" href="#kvm-hypercalls-documentation" title="Link to this heading">¶</a></h2>
<p>The template for each hypercall is:
1. Hypercall name.
2. Architecture(s)
3. Status (deprecated, obsolete, active)
4. Purpose</p>
<section id="kvm-hc-vapic-poll-irq">
<h3>1. KVM_HC_VAPIC_POLL_IRQ<a class="headerlink" href="#kvm-hc-vapic-poll-irq" title="Link to this heading">¶</a></h3>
<dl class="field-list simple">
<dt class="field-odd">Architecture<span class="colon">:</span></dt>
<dd class="field-odd"><p>x86</p>
</dd>
<dt class="field-even">Status<span class="colon">:</span></dt>
<dd class="field-even"><p>active</p>
</dd>
<dt class="field-odd">Purpose<span class="colon">:</span></dt>
<dd class="field-odd"><p>Trigger guest exit so that the host can check for pending
interrupts on reentry.</p>
</dd>
</dl>
</section>
<section id="kvm-hc-mmu-op">
<h3>2. KVM_HC_MMU_OP<a class="headerlink" href="#kvm-hc-mmu-op" title="Link to this heading">¶</a></h3>
<dl class="field-list simple">
<dt class="field-odd">Architecture<span class="colon">:</span></dt>
<dd class="field-odd"><p>x86</p>
</dd>
<dt class="field-even">Status<span class="colon">:</span></dt>
<dd class="field-even"><p>deprecated.</p>
</dd>
<dt class="field-odd">Purpose<span class="colon">:</span></dt>
<dd class="field-odd"><p>Support MMU operations such as writing to PTE,
flushing TLB, release PT.</p>
</dd>
</dl>
</section>
<section id="kvm-hc-features">
<h3>3. KVM_HC_FEATURES<a class="headerlink" href="#kvm-hc-features" title="Link to this heading">¶</a></h3>
<dl class="field-list simple">
<dt class="field-odd">Architecture<span class="colon">:</span></dt>
<dd class="field-odd"><p>PPC</p>
</dd>
<dt class="field-even">Status<span class="colon">:</span></dt>
<dd class="field-even"><p>active</p>
</dd>
<dt class="field-odd">Purpose<span class="colon">:</span></dt>
<dd class="field-odd"><p>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.</p>
</dd>
</dl>
</section>
<section id="kvm-hc-ppc-map-magic-page">
<h3>4. KVM_HC_PPC_MAP_MAGIC_PAGE<a class="headerlink" href="#kvm-hc-ppc-map-magic-page" title="Link to this heading">¶</a></h3>
<dl class="field-list simple">
<dt class="field-odd">Architecture<span class="colon">:</span></dt>
<dd class="field-odd"><p>PPC</p>
</dd>
<dt class="field-even">Status<span class="colon">:</span></dt>
<dd class="field-even"><p>active</p>
</dd>
<dt class="field-odd">Purpose<span class="colon">:</span></dt>
<dd class="field-odd"><p>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.</p>
</dd>
</dl>
</section>
<section id="kvm-hc-kick-cpu">
<h3>5. KVM_HC_KICK_CPU<a class="headerlink" href="#kvm-hc-kick-cpu" title="Link to this heading">¶</a></h3>
<dl class="field-list simple">
<dt class="field-odd">Architecture<span class="colon">:</span></dt>
<dd class="field-odd"><p>x86</p>
</dd>
<dt class="field-even">Status<span class="colon">:</span></dt>
<dd class="field-even"><p>active</p>
</dd>
<dt class="field-odd">Purpose<span class="colon">:</span></dt>
<dd class="field-odd"><p>Hypercall used to wakeup a vcpu from HLT state</p>
</dd>
<dt class="field-even">Usage example<span class="colon">:</span></dt>
<dd class="field-even"><p>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.</p>
</dd>
</dl>
</section>
<section id="kvm-hc-clock-pairing">
<h3>6. KVM_HC_CLOCK_PAIRING<a class="headerlink" href="#kvm-hc-clock-pairing" title="Link to this heading">¶</a></h3>
<dl class="field-list simple">
<dt class="field-odd">Architecture<span class="colon">:</span></dt>
<dd class="field-odd"><p>x86</p>
</dd>
<dt class="field-even">Status<span class="colon">:</span></dt>
<dd class="field-even"><p>active</p>
</dd>
<dt class="field-odd">Purpose<span class="colon">:</span></dt>
<dd class="field-odd"><p>Hypercall used to synchronize host and guest clocks.</p>
</dd>
</dl>
<p>Usage:</p>
<p>a0: guest physical address where host copies
“<code class="xref c c-struct broken_xref docutils literal notranslate"><span class="pre">struct</span> <span class="pre">kvm_clock_offset</span></code>” structure.</p>
<p>a1: clock_type, ATM only KVM_CLOCK_PAIRING_WALLCLOCK (0)
is supported (corresponding to the host’s CLOCK_REALTIME clock).</p>
<blockquote>
<div><div class="highlight-none notranslate"><div class="highlight"><pre><span></span>struct kvm_clock_pairing {
__s64 sec;
__s64 nsec;
__u64 tsc;
__u32 flags;
__u32 pad[9];
};
</pre></div>
</div>
<dl class="simple">
<dt>Where:</dt><dd><ul class="simple">
<li><p>sec: seconds from clock_type clock.</p></li>
<li><p>nsec: nanoseconds from clock_type clock.</p></li>
<li><p>tsc: guest TSC value used to calculate sec/nsec pair</p></li>
<li><p>flags: flags, unused (0) at the moment.</p></li>
</ul>
</dd>
</dl>
</div></blockquote>
<p>The hypercall lets a guest compute a precise timestamp across
host and guest. The guest can use the returned TSC value to
compute the CLOCK_REALTIME for its clock, at the same instant.</p>
<p>Returns KVM_EOPNOTSUPP if the host does not use TSC clocksource,
or if clock type is different than KVM_CLOCK_PAIRING_WALLCLOCK.</p>
</section>
<section id="kvm-hc-send-ipi">
<h3>7. KVM_HC_SEND_IPI<a class="headerlink" href="#kvm-hc-send-ipi" title="Link to this heading">¶</a></h3>
<dl class="field-list simple">
<dt class="field-odd">Architecture<span class="colon">:</span></dt>
<dd class="field-odd"><p>x86</p>
</dd>
<dt class="field-even">Status<span class="colon">:</span></dt>
<dd class="field-even"><p>active</p>
</dd>
<dt class="field-odd">Purpose<span class="colon">:</span></dt>
<dd class="field-odd"><p>Send IPIs to multiple vCPUs.</p>
</dd>
</dl>
<ul class="simple">
<li><p>a0: lower part of the bitmap of destination APIC IDs</p></li>
<li><p>a1: higher part of the bitmap of destination APIC IDs</p></li>
<li><p>a2: the lowest APIC ID in bitmap</p></li>
<li><p>a3: APIC ICR</p></li>
</ul>
<p>The hypercall lets a guest send multicast IPIs, with at most 128
128 destinations per hypercall in 64-bit mode and 64 vCPUs per
hypercall in 32-bit mode. The destinations are represented by a
bitmap contained in the first two arguments (a0 and a1). Bit 0 of
a0 corresponds to the APIC ID in the third argument (a2), bit 1
corresponds to the APIC ID a2+1, and so on.</p>
<p>Returns the number of CPUs to which the IPIs were delivered successfully.</p>
</section>
<section id="kvm-hc-sched-yield">
<h3>8. KVM_HC_SCHED_YIELD<a class="headerlink" href="#kvm-hc-sched-yield" title="Link to this heading">¶</a></h3>
<dl class="field-list simple">
<dt class="field-odd">Architecture<span class="colon">:</span></dt>
<dd class="field-odd"><p>x86</p>
</dd>
<dt class="field-even">Status<span class="colon">:</span></dt>
<dd class="field-even"><p>active</p>
</dd>
<dt class="field-odd">Purpose<span class="colon">:</span></dt>
<dd class="field-odd"><p>Hypercall used to yield if the IPI target vCPU is preempted</p>
</dd>
</dl>
<p>a0: destination APIC ID</p>
<dl class="field-list simple">
<dt class="field-odd">Usage example<span class="colon">:</span></dt>
<dd class="field-odd"><p>When sending a call-function IPI-many to vCPUs, yield if
any of the IPI target vCPUs was preempted.</p>
</dd>
</dl>
</section>
<section id="kvm-hc-map-gpa-range">
<h3>9. KVM_HC_MAP_GPA_RANGE<a class="headerlink" href="#kvm-hc-map-gpa-range" title="Link to this heading">¶</a></h3>
<dl class="field-list simple">
<dt class="field-odd">Architecture<span class="colon">:</span></dt>
<dd class="field-odd"><p>x86</p>
</dd>
<dt class="field-even">Status<span class="colon">:</span></dt>
<dd class="field-even"><p>active</p>
</dd>
<dt class="field-odd">Purpose<span class="colon">:</span></dt>
<dd class="field-odd"><p>Request KVM to map a GPA range with the specified attributes.</p>
</dd>
</dl>
<p>a0: the guest physical address of the start page
a1: the number of (4kb) pages (must be contiguous in GPA space)
a2: attributes</p>
<blockquote>
<div><dl class="simple">
<dt>Where ‘attributes’ :</dt><dd><ul class="simple">
<li><p>bits 3:0 - preferred page size encoding 0 = 4kb, 1 = 2mb, 2 = 1gb, etc...</p></li>
<li><p>bit 4 - plaintext = 0, encrypted = 1</p></li>
<li><p>bits 63:5 - reserved (must be zero)</p></li>
</ul>
</dd>
</dl>
</div></blockquote>
<p><strong>Implementation note</strong>: this hypercall is implemented in userspace via
the KVM_CAP_EXIT_HYPERCALL capability. Userspace must enable that capability
before advertising KVM_FEATURE_HC_MAP_GPA_RANGE in the guest CPUID. In
addition, if the guest supports KVM_FEATURE_MIGRATION_CONTROL, userspace
must also set up an MSR filter to process writes to MSR_KVM_MIGRATION_CONTROL.</p>
</section>
</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/x86/hypercalls.rst.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>