<!DOCTYPE html>
<html class="writer-html5" lang="en" >
<head>
<meta charset="utf-8" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>QEMU User Documentation — QEMU documentation</title>
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="../_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="../_static/theme_overrides.css" type="text/css" />
<link rel="shortcut icon" href="../_static/qemu_32x32.png"/>
<script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
<script src="../_static/jquery.js"></script>
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/custom.js"></script>
<script src="../_static/js/theme.js"></script>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" style="background: #802400" >
<a href="../index.html" class="icon icon-home"> QEMU
<img src="../_static/qemu_128x128.png" class="logo" alt="Logo"/>
</a>
<div class="version">
7.1.94
</div>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
<input type="text" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../about/index.html">About QEMU</a></li>
<li class="toctree-l1"><a class="reference internal" href="index.html">System Emulation</a></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>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" style="background: #802400" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="../index.html">QEMU</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="../index.html" class="icon icon-home"></a></li>
<li class="breadcrumb-item active">QEMU User Documentation</li>
<li class="wy-breadcrumbs-aside">
<a href="https://gitlab.com/qemu-project/qemu/blob/master/docs/system/qemu-manpage.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">
<section id="qemu-user-documentation">
<h1>QEMU User Documentation<a class="headerlink" href="#qemu-user-documentation" title="Permalink to this headline"></a></h1>
<section id="synopsis">
<h2>Synopsis<a class="headerlink" href="#synopsis" title="Permalink to this headline"></a></h2>
<pre class="literal-block">qemu-system-x86_64 [options] [disk_image]</pre>
</section>
<section id="description">
<h2>Description<a class="headerlink" href="#description" title="Permalink to this headline"></a></h2>
<p>The QEMU PC System emulator simulates the following peripherals:</p>
<ul class="simple">
<li><p>i440FX host PCI bridge and PIIX3 PCI to ISA bridge</p></li>
<li><p>Cirrus CLGD 5446 PCI VGA card or dummy VGA card with Bochs VESA
extensions (hardware level, including all non standard modes).</p></li>
<li><p>PS/2 mouse and keyboard</p></li>
<li><p>2 PCI IDE interfaces with hard disk and CD-ROM support</p></li>
<li><p>Floppy disk</p></li>
<li><p>PCI and ISA network adapters</p></li>
<li><p>Serial ports</p></li>
<li><p>IPMI BMC, either and internal or external one</p></li>
<li><p>Creative SoundBlaster 16 sound card</p></li>
<li><p>ENSONIQ AudioPCI ES1370 sound card</p></li>
<li><p>Intel 82801AA AC97 Audio compatible sound card</p></li>
<li><p>Intel HD Audio Controller and HDA codec</p></li>
<li><p>Adlib (OPL2) - Yamaha YM3812 compatible chip</p></li>
<li><p>Gravis Ultrasound GF1 sound card</p></li>
<li><p>CS4231A compatible sound card</p></li>
<li><p>PC speaker</p></li>
<li><p>PCI UHCI, OHCI, EHCI or XHCI USB controller and a virtual USB-1.1
hub.</p></li>
</ul>
<p>SMP is supported with up to 255 CPUs.</p>
<p>QEMU uses the PC BIOS from the Seabios project and the Plex86/Bochs LGPL
VGA BIOS.</p>
<p>QEMU uses YM3812 emulation by Tatsuyuki Satoh.</p>
<p>QEMU uses GUS emulation (GUSEMU32 <a class="reference external" href="http://www.deinmeister.de/gusemu/">http://www.deinmeister.de/gusemu/</a>) by
Tibor "TS" Schütz.</p>
<p>Note that, by default, GUS shares IRQ(7) with parallel ports and so QEMU
must be told to not have parallel ports to have working GUS.</p>
<pre class="literal-block">qemu-system-x86_64 dos.img -device gus -parallel none</pre>
<p>Alternatively:</p>
<pre class="literal-block">qemu-system-x86_64 dos.img -device gus,irq=5</pre>
<p>Or some other unclaimed IRQ.</p>
<p>CS4231A is the chip used in Windows Sound System and GUSMAX products</p>
<p>The PC speaker audio device can be configured using the pcspk-audiodev
machine property, i.e.</p>
<pre class="literal-block">qemu-system-x86_64 some.img -audiodev <backend>,id=<name> -machine pcspk-audiodev=<name></pre>
</section>
<section id="options">
<h2>Options<a class="headerlink" href="#options" title="Permalink to this headline"></a></h2>
<p>disk_image is a raw hard disk image for IDE hard disk 0. Some targets do
not need a disk image.</p>
<section id="hxtool-0">
<h3>Standard options<a class="headerlink" href="#hxtool-0" title="Permalink to this headline"></a></h3>
<dl>
<dt><code class="docutils literal notranslate"><span class="pre">-h</span></code></dt><dd><p>Display help and exit</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">-version</span></code></dt><dd><p>Display version information and exit</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">-machine</span> <span class="pre">[type=]name[,prop=value[,...]]</span></code></dt><dd><p>Select the emulated machine by name. Use <code class="docutils literal notranslate"><span class="pre">-machine</span> <span class="pre">help</span></code> to list
available machines.</p>
<p>For architectures which aim to support live migration compatibility
across releases, each release will introduce a new versioned machine
type. For example, the 2.8.0 release introduced machine types
“pc-i440fx-2.8” and “pc-q35-2.8” for the x86_64/i686 architectures.</p>
<p>To allow live migration of guests from QEMU version 2.8.0, to QEMU
version 2.9.0, the 2.9.0 version must support the “pc-i440fx-2.8”
and “pc-q35-2.8” machines too. To allow users live migrating VMs to
skip multiple intermediate releases when upgrading, new releases of
QEMU will support machine types from many previous versions.</p>
<p>Supported machine properties are:</p>
<dl>
<dt><code class="docutils literal notranslate"><span class="pre">accel=accels1[:accels2[:...]]</span></code></dt><dd><p>This is used to enable an accelerator. Depending on the target
architecture, kvm, xen, hax, hvf, nvmm, whpx or tcg can be available.
By default, tcg is used. If there is more than one accelerator
specified, the next one is used if the previous one fails to
initialize.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">vmport=on|off|auto</span></code></dt><dd><p>Enables emulation of VMWare IO port, for vmmouse etc. auto says
to select the value based on accel. For accel=xen the default is
off otherwise the default is on.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">dump-guest-core=on|off</span></code></dt><dd><p>Include guest memory in a core dump. The default is on.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">mem-merge=on|off</span></code></dt><dd><p>Enables or disables memory merge support. This feature, when
supported by the host, de-duplicates identical memory pages
among VMs instances (enabled by default).</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">aes-key-wrap=on|off</span></code></dt><dd><p>Enables or disables AES key wrapping support on s390-ccw hosts.
This feature controls whether AES wrapping keys will be created
to allow execution of AES cryptographic functions. The default
is on.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">dea-key-wrap=on|off</span></code></dt><dd><p>Enables or disables DEA key wrapping support on s390-ccw hosts.
This feature controls whether DEA wrapping keys will be created
to allow execution of DEA cryptographic functions. The default
is on.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">nvdimm=on|off</span></code></dt><dd><p>Enables or disables NVDIMM support. The default is off.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">memory-encryption=</span></code></dt><dd><p>Memory encryption object to use. The default is none.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">hmat=on|off</span></code></dt><dd><p>Enables or disables ACPI Heterogeneous Memory Attribute Table
(HMAT) support. The default is off.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">memory-backend='id'</span></code></dt><dd><p>An alternative to legacy <code class="docutils literal notranslate"><span class="pre">-mem-path</span></code> and <code class="docutils literal notranslate"><span class="pre">mem-prealloc</span></code> options.
Allows to use a memory backend as main RAM.</p>
<p>For 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">pc</span><span class="o">.</span><span class="n">ram</span><span class="p">,</span><span class="n">size</span><span class="o">=</span><span class="mi">512</span><span class="n">M</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">hugetlbfs</span><span class="p">,</span><span class="n">prealloc</span><span class="o">=</span><span class="n">on</span><span class="p">,</span><span class="n">share</span><span class="o">=</span><span class="n">on</span>
<span class="o">-</span><span class="n">machine</span> <span class="n">memory</span><span class="o">-</span><span class="n">backend</span><span class="o">=</span><span class="n">pc</span><span class="o">.</span><span class="n">ram</span>
<span class="o">-</span><span class="n">m</span> <span class="mi">512</span><span class="n">M</span>
</pre></div>
</div>
<p>Migration compatibility note:</p>
<ul class="simple">
<li><p>as backend id one shall use value of ‘default-ram-id’, advertised by
machine type (available via <code class="docutils literal notranslate"><span class="pre">query-machines</span></code> QMP command), if migration
to/from old QEMU (<5.0) is expected.</p></li>
<li><p>for machine types 4.0 and older, user shall
use <code class="docutils literal notranslate"><span class="pre">x-use-canonical-path-for-ramblock-id=off</span></code> backend option
if migration to/from old QEMU (<5.0) is expected.</p></li>
</ul>
<p>For 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">ram</span><span class="p">,</span><span class="nb">id</span><span class="o">=</span><span class="n">pc</span><span class="o">.</span><span class="n">ram</span><span class="p">,</span><span class="n">size</span><span class="o">=</span><span class="mi">512</span><span class="n">M</span><span class="p">,</span><span class="n">x</span><span class="o">-</span><span class="n">use</span><span class="o">-</span><span class="n">canonical</span><span class="o">-</span><span class="n">path</span><span class="o">-</span><span class="k">for</span><span class="o">-</span><span class="n">ramblock</span><span class="o">-</span><span class="nb">id</span><span class="o">=</span><span class="n">off</span>
<span class="o">-</span><span class="n">machine</span> <span class="n">memory</span><span class="o">-</span><span class="n">backend</span><span class="o">=</span><span class="n">pc</span><span class="o">.</span><span class="n">ram</span>
<span class="o">-</span><span class="n">m</span> <span class="mi">512</span><span class="n">M</span>
</pre></div>
</div>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">cxl-fmw.0.targets.0=firsttarget,cxl-fmw.0.targets.1=secondtarget,cxl-fmw.0.size=size[,cxl-fmw.0.interleave-granularity=granularity]</span></code></dt><dd><p>Define a CXL Fixed Memory Window (CFMW).</p>
<p>Described in the CXL 2.0 ECN: CEDT CFMWS & QTG _DSM.</p>
<p>They are regions of Host Physical Addresses (HPA) on a system which
may be interleaved across one or more CXL host bridges. The system
software will assign particular devices into these windows and
configure the downstream Host-managed Device Memory (HDM) decoders
in root ports, switch ports and devices appropriately to meet the
interleave requirements before enabling the memory devices.</p>
<p><code class="docutils literal notranslate"><span class="pre">targets.X=target</span></code> provides the mapping to CXL host bridges
which may be identified by the id provided in the -device entry.
Multiple entries are needed to specify all the targets when
the fixed memory window represents interleaved memory. X is the
target index from 0.</p>
<p><code class="docutils literal notranslate"><span class="pre">size=size</span></code> sets the size of the CFMW. This must be a multiple of
256MiB. The region will be aligned to 256MiB but the location is
platform and configuration dependent.</p>
<p><code class="docutils literal notranslate"><span class="pre">interleave-granularity=granularity</span></code> sets the granularity of
interleave. Default 256KiB. Only 256KiB, 512KiB, 1024KiB, 2048KiB
4096KiB, 8192KiB and 16384KiB granularities supported.</p>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">-</span><span class="n">machine</span> <span class="n">cxl</span><span class="o">-</span><span class="n">fmw</span><span class="mf">.0</span><span class="o">.</span><span class="n">targets</span><span class="mf">.0</span><span class="o">=</span><span class="n">cxl</span><span class="mf">.0</span><span class="p">,</span><span class="n">cxl</span><span class="o">-</span><span class="n">fmw</span><span class="mf">.0</span><span class="o">.</span><span class="n">targets</span><span class="mf">.1</span><span class="o">=</span><span class="n">cx