One Hat Cyber Team

Edit File: virtio-pmem.html

<!DOCTYPE html>

 <html class="no-js" lang="en" > 
<head>
  <meta charset="utf-8">
  
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  
  <title>virtio pmem &mdash; QEMU qemu-kvm-6.2.0-53.module+el8.10.0+2055+8eb7870b.4 documentation</title>

</head>

<a href="../../index.html" class="icon icon-home"> QEMU

</div>

<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
          
            
            
              
            
            
              <p class="caption"><span class="caption-text">Contents:</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../../about/index.html">About QEMU</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../index.html">System Emulation</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../quickstart.html">Quick Start</a></li>
<li class="toctree-l2"><a class="reference internal" href="../invocation.html">Invocation</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="../device-emulation.html">Device Emulation</a><ul class="current">
<li class="toctree-l3"><a class="reference internal" href="../device-emulation.html#common-terms">Common Terms</a></li>
<li class="toctree-l3 current"><a class="reference internal" href="../device-emulation.html#emulated-devices">Emulated Devices</a><ul class="current">
<li class="toctree-l4"><a class="reference internal" href="ivshmem.html">Inter-VM Shared Memory device</a></li>
<li class="toctree-l4"><a class="reference internal" href="net.html">Network emulation</a></li>
<li class="toctree-l4"><a class="reference internal" href="nvme.html">NVMe Emulation</a></li>
<li class="toctree-l4"><a class="reference internal" href="usb.html">USB emulation</a></li>
<li class="toctree-l4"><a class="reference internal" href="vhost-user.html">vhost-user back ends</a></li>
<li class="toctree-l4 current"><a class="current reference internal" href="#">virtio pmem</a></li>
<li class="toctree-l4"><a class="reference internal" href="vhost-user-rng.html">QEMU vhost-user-rng - RNG emulation</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../keys.html">Keys in the graphical frontends</a></li>
<li class="toctree-l2"><a class="reference internal" href="../mux-chardev.html">Keys in the character backend multiplexer</a></li>
<li class="toctree-l2"><a class="reference internal" href="../monitor.html">QEMU Monitor</a></li>
<li class="toctree-l2"><a class="reference internal" href="../images.html">Disk Images</a></li>
<li class="toctree-l2"><a class="reference internal" href="../virtio-net-failover.html">QEMU virtio-net standby (net_failover)</a></li>
<li class="toctree-l2"><a class="reference internal" href="../linuxboot.html">Direct Linux Boot</a></li>
<li class="toctree-l2"><a class="reference internal" href="../generic-loader.html">Generic Loader</a></li>
<li class="toctree-l2"><a class="reference internal" href="../guest-loader.html">Guest Loader</a></li>
<li class="toctree-l2"><a class="reference internal" href="../barrier.html">QEMU Barrier Client</a></li>
<li class="toctree-l2"><a class="reference internal" href="../vnc-security.html">VNC security</a></li>
<li class="toctree-l2"><a class="reference internal" href="../tls.html">TLS setup for network services</a></li>
<li class="toctree-l2"><a class="reference internal" href="../secrets.html">Providing secret data to QEMU</a></li>
<li class="toctree-l2"><a class="reference internal" href="../authz.html">Client authorization</a></li>
<li class="toctree-l2"><a class="reference internal" href="../gdb.html">GDB usage</a></li>
<li class="toctree-l2"><a class="reference internal" href="../managed-startup.html">Managed start up options</a></li>
<li class="toctree-l2"><a class="reference internal" href="../bootindex.html">Managing device boot order with bootindex properties</a></li>
<li class="toctree-l2"><a class="reference internal" href="../cpu-hotplug.html">Virtual CPU hotplug</a></li>
<li class="toctree-l2"><a class="reference internal" href="../pr-manager.html">Persistent reservation managers</a></li>
<li class="toctree-l2"><a class="reference internal" href="../targets.html">QEMU System Emulator Targets</a></li>
<li class="toctree-l2"><a class="reference internal" href="../security.html">Security</a></li>
<li class="toctree-l2"><a class="reference internal" href="../multi-process.html">Multi-process QEMU</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../user/index.html">User Mode Emulation</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../tools/index.html">Tools</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../interop/index.html">System Emulation Management and Interoperability</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../specs/index.html">System Emulation Guest Hardware Specifications</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../devel/index.html">Developer Information</a></li>
</ul>

</div>
      </div>
    </nav>

<ul class="wy-breadcrumbs">
    
      <li><a href="../../index.html">Docs</a> &raquo;</li>
        
          <li><a href="../index.html">System Emulation</a> &raquo;</li>
        
          <li><a href="../device-emulation.html">Device Emulation</a> &raquo;</li>
        
      <li>virtio pmem</li>
    
    
      <li class="wy-breadcrumbs-aside">
        
            
            
              <a href="https://gitlab.com/qemu-project/qemu/blob/master/docs/system/devices/virtio-pmem.rst" class="fa fa-gitlab"> Edit on GitLab</a>
            
          
        
      </li>
    
  </ul>

<hr/>
</div>
          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
           <div itemprop="articleBody">
            
  <div class="section" id="virtio-pmem">
<h1>virtio pmem<a class="headerlink" href="#virtio-pmem" title="Permalink to this headline">¶</a></h1>
<p>This document explains the setup and usage of the virtio pmem device.
The virtio pmem device is a paravirtualized persistent memory device
on regular (i.e non-NVDIMM) storage.</p>
<div class="section" id="usecase">
<h2>Usecase<a class="headerlink" href="#usecase" title="Permalink to this headline">¶</a></h2>
<p>Virtio pmem allows to bypass the guest page cache and directly use
host page cache. This reduces guest memory footprint as the host can
make efficient memory reclaim decisions under memory pressure.</p>
</div>
<div class="section" id="how-does-virtio-pmem-compare-to-the-nvdimm-emulation">
<h2>How does virtio-pmem compare to the nvdimm emulation?<a class="headerlink" href="#how-does-virtio-pmem-compare-to-the-nvdimm-emulation" title="Permalink to this headline">¶</a></h2>
<p>NVDIMM emulation on regular (i.e. non-NVDIMM) host storage does not
persist the guest writes as there are no defined semantics in the device
specification. The virtio pmem device provides guest write persistence
on non-NVDIMM host storage.</p>
</div>
<div class="section" id="virtio-pmem-usage">
<h2>virtio pmem usage<a class="headerlink" href="#virtio-pmem-usage" title="Permalink to this headline">¶</a></h2>
<p>A virtio pmem device backed by a memory-backend-file can be created on
the QEMU command line as in the following example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">-</span><span class="nb">object</span> <span class="n">memory</span><span class="o">-</span><span class="n">backend</span><span class="o">-</span><span class="n">file</span><span class="p">,</span><span class="nb">id</span><span class="o">=</span><span class="n">mem1</span><span class="p">,</span><span class="n">share</span><span class="p">,</span><span class="n">mem</span><span class="o">-</span><span class="n">path</span><span class="o">=./</span><span class="n">virtio_pmem</span><span class="o">.</span><span class="n">img</span><span class="p">,</span><span class="n">size</span><span class="o">=</span><span class="mi">4</span><span class="n">G</span>
<span class="o">-</span><span class="n">device</span> <span class="n">virtio</span><span class="o">-</span><span class="n">pmem</span><span class="o">-</span><span class="n">pci</span><span class="p">,</span><span class="n">memdev</span><span class="o">=</span><span class="n">mem1</span><span class="p">,</span><span class="nb">id</span><span class="o">=</span><span class="n">nv1</span>
</pre></div>
</div>
<p>where:</p>
<blockquote>
<div><ul class="simple">
<li>“object memory-backend-file,id=mem1,share,mem-path=&lt;image&gt;, size=&lt;image size&gt;”
creates a backend file with the specified size.</li>
<li>“device virtio-pmem-pci,id=nvdimm1,memdev=mem1” creates a virtio pmem
pci device whose storage is provided by above memory backend device.</li>
</ul>
</div></blockquote>
<p>Multiple virtio pmem devices can be created if multiple pairs of “-object”
and “-device” are provided.</p>
</div>
<div class="section" id="hotplug">
<h2>Hotplug<a class="headerlink" href="#hotplug" title="Permalink to this headline">¶</a></h2>
<p>Virtio pmem devices can be hotplugged via the QEMU monitor. First, the
memory backing has to be added via ‘object_add’; afterwards, the virtio
pmem device can be added via ‘device_add’.</p>
<p>For example, the following commands add another 4GB virtio pmem device to
the guest:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">(</span><span class="n">qemu</span><span class="p">)</span> <span class="n">object_add</span> <span class="n">memory</span><span class="o">-</span><span class="n">backend</span><span class="o">-</span><span class="n">file</span><span class="p">,</span><span class="nb">id</span><span class="o">=</span><span class="n">mem2</span><span class="p">,</span><span class="n">share</span><span class="o">=</span><span class="n">on</span><span class="p">,</span><span class="n">mem</span><span class="o">-</span><span class="n">path</span><span class="o">=</span><span class="n">virtio_pmem2</span><span class="o">.</span><span class="n">img</span><span class="p">,</span><span class="n">size</span><span class="o">=</span><span class="mi">4</span><span class="n">G</span>
<span class="p">(</span><span class="n">qemu</span><span class="p">)</span> <span class="n">device_add</span> <span class="n">virtio</span><span class="o">-</span><span class="n">pmem</span><span class="o">-</span><span class="n">pci</span><span class="p">,</span><span class="nb">id</span><span class="o">=</span><span class="n">virtio_pmem2</span><span class="p">,</span><span class="n">memdev</span><span class="o">=</span><span class="n">mem2</span>
</pre></div>
</div>
</div>
<div class="section" id="guest-data-persistence">
<h2>Guest Data Persistence<a class="headerlink" href="#guest-data-persistence" title="Permalink to this headline">¶</a></h2>
<p>Guest data persistence on non-NVDIMM requires guest userspace applications
to perform fsync/msync. This is different from a real nvdimm backend where
no additional fsync/msync is required. This is to persist guest writes in
host backing file which otherwise remains in host page cache and there is
risk of losing the data in case of power failure.</p>
<p>With virtio pmem device, MAP_SYNC mmap flag is not supported. This provides
a hint to application to perform fsync for write persistence.</p>
</div>
<div class="section" id="limitations">
<h2>Limitations<a class="headerlink" href="#limitations" title="Permalink to this headline">¶</a></h2>
<ul class="simple">
<li>Real nvdimm device backend is not supported.</li>
<li>virtio pmem hotunplug is not supported.</li>
<li>ACPI NVDIMM features like regions/namespaces are not supported.</li>
<li>ndctl command is not supported.</li>
</ul>
</div>
</div>

</div>
           
          </div>
          <footer>
  
    <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
      
        <a href="vhost-user-rng.html" class="btn btn-neutral float-right" title="QEMU vhost-user-rng - RNG emulation" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right"></span></a>
      
      
        <a href="vhost-user.html" class="btn btn-neutral" title="vhost-user back ends" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left"></span> Previous</a>
      
    </div>

<hr/>

<div role="contentinfo">
    <p>
        &copy; Copyright 2021, The QEMU Project Developers.

</p>
  </div>
  Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/rtfd/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.

<p></p>

<p>This documentation is for QEMU version 6.2.0.</p>

<p><a href="../../about/license.html">QEMU and this manual are released under the
GNU General Public License, version 2.</a></p>

</footer>

</div>
      </div>

</section>

</div>

</body>
</html>