One Hat Cyber Team

Edit File: decodetree.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>Decodetree Specification &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">
 
 
 
 
 
 
 Contents:
<ul class="current">
<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="../system/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 current"><a class="reference internal" href="index.html">Developer Information</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="code-of-conduct.html">Code of Conduct</a></li>
<li class="toctree-l2"><a class="reference internal" href="conflict-resolution.html">Conflict Resolution Policy</a></li>
<li class="toctree-l2"><a class="reference internal" href="build-system.html">The QEMU build system architecture</a></li>
<li class="toctree-l2"><a class="reference internal" href="style.html">QEMU Coding Style</a></li>
<li class="toctree-l2"><a class="reference internal" href="kconfig.html">QEMU and Kconfig</a></li>
<li class="toctree-l2"><a class="reference internal" href="testing.html">Testing in QEMU</a></li>
<li class="toctree-l2"><a class="reference internal" href="fuzzing.html">Fuzzing</a></li>
<li class="toctree-l2"><a class="reference internal" href="control-flow-integrity.html">Control-Flow Integrity (CFI)</a></li>
<li class="toctree-l2"><a class="reference internal" href="loads-stores.html">Load and Store APIs</a></li>
<li class="toctree-l2"><a class="reference internal" href="memory.html">The memory API</a></li>
<li class="toctree-l2"><a class="reference internal" href="migration.html">Migration</a></li>
<li class="toctree-l2"><a class="reference internal" href="atomics.html">Atomic operations in QEMU</a></li>
<li class="toctree-l2"><a class="reference internal" href="stable-process.html">QEMU and the stable process</a></li>
<li class="toctree-l2"><a class="reference internal" href="ci.html">CI</a></li>
<li class="toctree-l2"><a class="reference internal" href="qtest.html">QTest Device Emulation Testing Framework</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">Decodetree Specification</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#fields">Fields</a></li>
<li class="toctree-l3"><a class="reference internal" href="#argument-sets">Argument Sets</a></li>
<li class="toctree-l3"><a class="reference internal" href="#formats">Formats</a></li>
<li class="toctree-l3"><a class="reference internal" href="#patterns">Patterns</a></li>
<li class="toctree-l3"><a class="reference internal" href="#pattern-groups">Pattern Groups</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="secure-coding-practices.html">Secure Coding Practices</a></li>
<li class="toctree-l2"><a class="reference internal" href="tcg.html">Translator Internals</a></li>
<li class="toctree-l2"><a class="reference internal" href="tcg-icount.html">TCG Instruction Counting</a></li>
<li class="toctree-l2"><a class="reference internal" href="tracing.html">Tracing</a></li>
<li class="toctree-l2"><a class="reference internal" href="multi-thread-tcg.html">Multi-threaded TCG</a></li>
<li class="toctree-l2"><a class="reference internal" href="tcg-plugins.html">QEMU TCG Plugins</a></li>
<li class="toctree-l2"><a class="reference internal" href="bitops.html">Bitwise operations</a></li>
<li class="toctree-l2"><a class="reference internal" href="ui.html">QEMU UI subsystem</a></li>
<li class="toctree-l2"><a class="reference internal" href="reset.html">Reset in QEMU: the Resettable interface</a></li>
<li class="toctree-l2"><a class="reference internal" href="s390-dasd-ipl.html">Booting from real channel-attached devices on s390x</a></li>
<li class="toctree-l2"><a class="reference internal" href="clocks.html">Modelling a clock tree in QEMU</a></li>
<li class="toctree-l2"><a class="reference internal" href="qom.html">The QEMU Object Model (QOM)</a></li>
<li class="toctree-l2"><a class="reference internal" href="modules.html">QEMU modules</a></li>
<li class="toctree-l2"><a class="reference internal" href="block-coroutine-wrapper.html">block-coroutine-wrapper</a></li>
<li class="toctree-l2"><a class="reference internal" href="multi-process.html">Multi-process QEMU</a></li>
<li class="toctree-l2"><a class="reference internal" href="ebpf_rss.html">eBPF RSS virtio-net support</a></li>
<li class="toctree-l2"><a class="reference internal" href="vfio-migration.html">VFIO device Migration</a></li>
<li class="toctree-l2"><a class="reference internal" href="qapi-code-gen.html">How to use the QAPI code generator</a></li>
<li class="toctree-l2"><a class="reference internal" href="writing-monitor-commands.html">How to write monitor commands</a></li>
<li class="toctree-l2"><a class="reference internal" href="trivial-patches.html">Trivial Patches</a></li>
<li class="toctree-l2"><a class="reference internal" href="submitting-a-patch.html">Submitting a Patch</a></li>
<li class="toctree-l2"><a class="reference internal" href="submitting-a-pull-request.html">Submitting a Pull Request</a></li>
</ul>
</li>
</ul>

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

<ul class="wy-breadcrumbs">
 
 <li><a href="../index.html">Docs</a> &raquo;</li>
 
 <li><a href="index.html">Developer Information</a> &raquo;</li>
 
 <li>Decodetree Specification</li>
 
 
 <li class="wy-breadcrumbs-aside">
 
 
 
 <a href="https://gitlab.com/qemu-project/qemu/blob/master/docs/devel/decodetree.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="decodetree-specification">
<h1>Decodetree Specification<a class="headerlink" href="#decodetree-specification" title="Permalink to this headline">¶</a></h1>
A decodetree is built from instruction patterns. A pattern may
represent a single architectural instruction or a group of same, depending
on what is convenient for further processing.
Each pattern has both fixedbits and fixedmask, the combination of which
describes the condition under which the pattern is matched:
<div class="highlight-default notranslate"><div class="highlight"><pre>(insn &amp; fixedmask) == fixedbits
</pre></div>
</div>
Each pattern may have fields, which are extracted from the insn and
passed along to the translator. Examples of such are registers,
immediates, and sub-opcodes.
In support of patterns, one may declare fields, argument sets, and
formats, each of which may be re-used to simplify further definitions.
<div class="section" id="fields">
<h2>Fields<a class="headerlink" href="#fields" title="Permalink to this headline">¶</a></h2>
Syntax:
<div class="highlight-default notranslate"><div class="highlight"><pre>field_def := &#39;%&#39; identifier ( unnamed_field )* ( !function=identifier )?
unnamed_field := number &#39;:&#39; ( &#39;s&#39; ) number
</pre></div>
</div>
For unnamed_field, the first number is the least-significant bit position
of the field and the second number is the length of the field. If the ‘s’ is
present, the field is considered signed. If multiple <code class="docutils literal notranslate">unnamed_fields</code> are
present, they are concatenated. In this way one can define disjoint fields.
If <code class="docutils literal notranslate">!function</code> is specified, the concatenated result is passed through the
named function, taking and returning an integral value.
One may use <code class="docutils literal notranslate">!function</code> with zero <code class="docutils literal notranslate">unnamed_fields</code>. This case is called
a parameter, and the named function is only passed the <code class="docutils literal notranslate">DisasContext</code>
and returns an integral value extracted from there.
A field with no <code class="docutils literal notranslate">unnamed_fields</code> and no <code class="docutils literal notranslate">!function</code> is in error.
Field examples:
<table border="1" class="docutils">
<colgroup>
<col width="38%" />
<col width="63%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Input</th>
<th class="head">Generated code</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>%disp 0:s16</td>
<td>sextract(i, 0, 16)</td>
</tr>
<tr class="row-odd"><td>%imm9 16:6 10:3</td>
<td>extract(i, 16, 6) &lt;&lt; 3 | extract(i, 10, 3)</td>
</tr>
<tr class="row-even"><td>%disp12 0:s1 1:1 2:10</td>
<td><dl class="first last docutils">
<dt>sextract(i, 0, 1) &lt;&lt; 11 |</dt>
<dd>extract(i, 1, 1) &lt;&lt; 10 |
extract(i, 2, 10)</dd>
</dl>
</td>
</tr>
<tr class="row-odd"><td><dl class="first last docutils">
<dt>%shimm8 5:s8 13:1</dt>
<dd>!function=expand_shimm8</dd>
</dl>
</td>
<td><dl class="first last docutils">
<dt>expand_shimm8(sextract(i, 5, 8) &lt;&lt; 1 |</dt>
<dd>extract(i, 13, 1))</dd>
</dl>
</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="argument-sets">
<h2>Argument Sets<a class="headerlink" href="#argument-sets" title="Permalink to this headline">¶</a></h2>
Syntax:
<div class="highlight-default notranslate"><div class="highlight"><pre>args_def := &#39;&amp;&#39; identifier ( args_elt )+ ( !extern )?
args_elt := identifier (&#39;:&#39; identifier)?
</pre></div>
</div>
Each args_elt defines an argument within the argument set.
If the form of the args_elt contains a colon, the first
identifier is the argument name and the second identifier is
the argument type. If the colon is missing, the argument
type will be <code class="docutils literal notranslate">int</code>.
Each argument set will be rendered as a C structure “arg_$name”
with each of the fields being one of the member arguments.
If <code class="docutils literal notranslate">!extern</code> is specified, the backing structure is assumed
to have been already declared, typically via a second decoder.
Argument sets are useful when one wants to define helper functions
for the translator functions that can perform operations on a common
set of arguments. This can ensure, for instance, that the <code class="docutils literal notranslate">AND</code>
pattern and the <code class="docutils literal notranslate">OR</code> pattern put their operands into the same named
structure, so that a common <code class="docutils literal notranslate">gen_logic_insn</code> may be able to handle
the operations common between the two.
Argument set examples:
<div class="highlight-default notranslate"><div class="highlight"><pre>&amp;reg3 ra rb rc
&amp;loadstore reg base offset
&amp;longldst reg base offset:int64_t
</pre></div>
</div>
</div>
<div class="section" id="formats">
<h2>Formats<a class="headerlink" href="#formats" title="Permalink to this headline">¶</a></h2>
Syntax:
<div class="highlight-default notranslate"><div class="highlight"><pre>fmt_def := &#39;@&#39; identifier ( fmt_elt )+
fmt_elt := fixedbit_elt | field_elt | field_ref | args_ref
fixedbit_elt := [01.-]+
field_elt := identifier &#39;:&#39; &#39;s&#39;? number
field_ref := &#39;%&#39; identifier | identifier &#39;=&#39; &#39;%&#39; identifier
args_ref := &#39;&amp;&#39; identifier
</pre></div>
</div>
Defining a format is a handy way to avoid replicating groups of fields
across many instruction patterns.
A fixedbit_elt describes a contiguous sequence of bits that must
be 1, 0, or don’t care. The difference between ‘.’ and ‘-‘
is that ‘.’ means that the bit will be covered with a field or a
final 0 or 1 from the pattern, and ‘-‘ means that the bit is really
ignored by the cpu and will not be specified.
A field_elt describes a simple field only given a width; the position of
the field is implied by its position with respect to other fixedbit_elt
and field_elt.
If any fixedbit_elt or field_elt appear, then all bits must be defined.
Padding with a fixedbit_elt of all ‘.’ is an easy way to accomplish that.
A field_ref incorporates a field by reference. This is the only way to
add a complex field to a format. A field may be renamed in the process
via assignment to another identifier. This is intended to allow the
same argument set be used with disjoint named fields.
A single args_ref may specify an argument set to use for the format.
The set of fields in the format must be a subset of the arguments in
the argument set. If an argument set is not specified, one will be
inferred from the set of fields.
It is recommended, but not required, that all field_ref and args_ref
appear at the end of the line, not interleaving with fixedbit_elf or
field_elt.
Format examples:
<div class="highlight-default notranslate"><div class="highlight"><pre>@opr ...... ra:5 rb:5 ... 0 ....... rc:5
@opi ...... ra:5 lit:8 1 ....... rc:5
</pre></div>
</div>
</div>
<div class="section" id="patterns">
<h2>Patterns<a class="headerlink" href="#patterns" title="Permalink to this headline">¶</a></h2>
Syntax:
<div class="highlight-default notranslate"><div class="highlight"><pre>pat_def := identifier ( pat_elt )+
pat_elt := fixedbit_elt | field_elt | field_ref | args_ref | fmt_ref | const_elt
fmt_ref := &#39;@&#39; identifier
const_elt := identifier &#39;=&#39; number
</pre></div>
</div>
The fixedbit_elt and field_elt specifiers are unchanged from formats.
A pattern that does not specify a named format will have one inferred
from a referenced argument set (if present) and the set of fields.
A const_elt allows a argument to be set to a constant value. This may
come in handy when fields overlap between patterns and one has to
include the values in the fixedbit_elt instead.
The decoder will call a translator function for each pattern matched.
Pattern examples:
<div class="highlight-default notranslate"><div class="highlight"><pre>addl_r 010000 ..... ..... .... 0000000 ..... @opr
addl_i 010000 ..... ..... .... 0000000 ..... @opi
</pre></div>
</div>
which will, in part, invoke:
<div class="highlight-default notranslate"><div class="highlight"><pre>trans_addl_r(ctx, &amp;arg_opr, insn)
</pre></div>
</div>
and:
<div class="highlight-default notranslate"><div class="highlight"><pre>trans_addl_i(ctx, &amp;arg_opi, insn)
</pre></div>
</div>
</div>
<div class="section" id="pattern-groups">
<h2>Pattern Groups<a class="headerlink" href="#pattern-groups" title="Permalink to this headline">¶</a></h2>
Syntax:
<div class="highlight-default notranslate"><div class="highlight"><pre>group := overlap_group | no_overlap_group
overlap_group := &#39;{&#39; ( pat_def | group )+ &#39;}&#39;
no_overlap_group := &#39;[&#39; ( pat_def | group )+ &#39;]&#39;
</pre></div>
</div>
A group begins with a lone open-brace or open-bracket, with all
subsequent lines indented two spaces, and ending with a lone
close-brace or close-bracket. Groups may be nested, increasing the
required indentation of the lines within the nested group to two
spaces per nesting level.
Patterns within overlap groups are allowed to overlap. Conflicts are
resolved by selecting the patterns in order. If all of the fixedbits
for a pattern match, its translate function will be called. If the
translate function returns false, then subsequent patterns within the
group will be matched.
Patterns within no-overlap groups are not allowed to overlap, just
the same as ungrouped patterns. Thus no-overlap groups are intended
to be nested inside overlap groups.
The following example from PA-RISC shows specialization of the or
instruction:
<div class="highlight-default notranslate"><div class="highlight"><pre>{
 {
 nop 000010 ----- ----- 0000 001001 0 00000
 copy 000010 00000 r1:5 0000 001001 0 rt:5
 }
 or 000010 rt2:5 r1:5 cf:4 001001 0 rt:5
}
</pre></div>
</div>
When the cf field is zero, the instruction has no side effects,
and may be specialized. When the rt field is zero, the output
is discarded and so the instruction has no effect. When the rt2
field is zero, the operation is <code class="docutils literal notranslate">reg[r1] | 0</code> and so encodes
the canonical register copy operation.
The output from the generator might look like:
<div class="highlight-default notranslate"><div class="highlight"><pre>switch (insn &amp; 0xfc000fe0) {
case 0x08000240:
 /* 000010.. ........ ....0010 010..... */
 if ((insn &amp; 0x0000f000) == 0x00000000) {
 /* 000010.. ........ 00000010 010..... */
 if ((insn &amp; 0x0000001f) == 0x00000000) {
 /* 000010.. ........ 00000010 01000000 */
 extract_decode_Fmt_0(&amp;u.f_decode0, insn);
 if (trans_nop(ctx, &amp;u.f_decode0)) return true;
 }
 if ((insn &amp; 0x03e00000) == 0x00000000) {
 /* 00001000 000..... 00000010 010..... */
 extract_decode_Fmt_1(&amp;u.f_decode1, insn);
 if (trans_copy(ctx, &amp;u.f_decode1)) return true;
 }
 }
 extract_decode_Fmt_2(&amp;u.f_decode2, insn);
 if (trans_or(ctx, &amp;u.f_decode2)) return true;
 return false;
}
</pre></div>
</div>
</div>
</div>

</div>
 
 </div>
 <footer>
 
 <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
 
 <a href="secure-coding-practices.html" class="btn btn-neutral float-right" title="Secure Coding Practices" accesskey="n" rel="next">Next </a>
 
 
 <a href="qgraph.html" class="btn btn-neutral" title="Qtest Driver Framework" accesskey="p" rel="prev"> Previous</a>
 
 </div>

<hr/>

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

</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>.

This documentation is for QEMU version 6.2.0.

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

</footer>

</div>
 </div>

</section>

</div>

</body>
</html>