Ghidra is a software reverse engineering (SRE) framework
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE book [
<!ENTITY emsp " "> <!-- Embedded space -->
<!ENTITY nbsp " "> <!-- Non-breaking space -->
]>
<book xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
<info>
<title>Decompiler</title>
</info>
<chapter id="DecompilerIntro">
<title>Decompiler</title>
<mediaobject>
<imageobject>
<imagedata condition="noscaling" fileref="images/DecompWindow.png" width="100%" contentwidth="1000px" contentdepth="391px" align="center"/>
<imagedata condition="withscaling" fileref="images/DecompWindow.png" width="100%" contentwidth="6.0in" contentdepth="2.346in" align="center"/>
</imageobject>
</mediaobject>
<section id="Overview">
<title>Overview</title>
<para>
The Decompiler plug-in is a sophisticated transformation engine
which automatically converts the binary representation of
individual functions into a high-level C representation. The
Decompiler presents a view of a program which is interactive and
dynamically updated as the user adds or makes changes to the
annotations associated with the program. A Decompiler window
maintains the correspondence between the C representation and the
assembly representation displayed in the Code Browser window, to
the extent possible. The window allows instant visual association
and navigation between C language expressions and their
corresponding assembly instructions.
</para>
<sect2 id="EnablePlugin">
<title>Enabling the Plug-in</title>
<para>
The Decompiler is a full Plug-in within Ghidra and can be configured to be enabled or
disabled within any particular tool. Default configurations will have the
plug-in enabled, but if it is disabled for some reason, it can be enabled from within
a Code Browser by selecting the
<informalexample>
<emphasis role="bold">File -> Configure...</emphasis>
</informalexample>
menu option, then clicking on the <emphasis>Configure</emphasis> link under the
<emphasis role="bold">Ghidra Core</emphasis> section and checking the box next to
<emphasis role="bold">DecompilePlugin</emphasis>.
</para>
</sect2>
<sect2 id="TriggerDecompilation">
<title>Decompiling a Function</title>
<para>
From the Code Browser, to open a Decompiler window, either:
<informalexample>
<itemizedlist mark='bullet'>
<listitem>
Press the <guiicon>
<inlinemediaobject>
<imageobject>
<imagedata condition="noscaling" fileref="images/decompileFunction.gif" contentwidth="16px" contentdepth="16px"/>
<imagedata condition="withscaling" fileref="images/decompileFunction.gif" contentwidth="0.15in" contentdepth="0.15in"/>
</imageobject>
</inlinemediaobject>
</guiicon> icon
in the tool bar, <emphasis>or</emphasis>
</listitem>
<listitem>
Select the <emphasis role="bold">Decompile</emphasis> option from the
<emphasis role="bold">Window</emphasis> menu.
</listitem>
</itemizedlist>
</informalexample>
</para>
<para>
The window automatically decompiles and displays the function at the
<emphasis>current address</emphasis>. The address is set typically by left-clicking in the Listing,
or invoking the <emphasis>Go To...</emphasis> command (pressing the 'G' key) and manually entering
the address or some other label, but the Decompiler window
follows any type of navigation in the Code Browser, triggering decompilation of the new function
being displayed.
</para>
<tip>
Any change to the function or Program made while using Ghidra causes the window to automatically
redecompile the function it is displaying, to incorporate the new information. Changes include (but
aren't limited to):
<itemizedlist mark='none'>
<listitem><link linkend="ActionRenameVariable">Renaming Variables</link></listitem>
<listitem><link linkend="ActionRetypeVariable">Setting Data-types</link></listitem>
<listitem><link linkend="ActionComments">Commenting</link></listitem>
<listitem><link linkend="ActionEditSignature">Setting a Function's Prototype</link></listitem>
</itemizedlist>
Users can control decompilation in a wide variety of ways, see <xref linkend="DecompilerAnnotations"/>.
</tip>
</sect2>
<sect2 id="Capabilities">
<title>Capabilities</title>
<para>
Some of the primary capabilities of the Decompiler include:
<informalexample>
<variablelist>
<?dbfo list-presentation="blocks"?>
<varlistentry>
<term><emphasis role="bold">Recovering Expressions</emphasis></term>
<listitem>
<para>
The Decompiler does full data-flow analysis which allows it to
perform slicing on functions: complicated expressions, which have been split into
distinct operations/instructions and then mixed together with
other instructions by the compiling/optimizing process, are
reconstituted back into a single line.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">Recovering High-Level Scoped Variables</emphasis></term>
<listitem>
<para>
The Decompiler understands how compilers
use processor stacks and registers to implement variables with
different scopes within a function. Data-flow analysis allows it to
follow what was originally a single variable as it moves from
the stack, into a register, into a different register, etc. Thus
it can effectively recover the original program's concept of a
variable, minimizing the need to introduce artificial variables
in the output.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">Recovering Function Parameters</emphasis></term>
<listitem>
<para>
The Decompiler understands the parameter-passing conventions of
the compiler and can reconstruct the original form of
function calls.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">Using Data-type, Name, and Signature Annotations</emphasis></term>
<listitem>
<para>
The Decompiler automatically pulls in
all the different data types and variable names that the user
has applied to functions, and the C output is altered to reflect
this. High-level variables are appropriately named, structure
fields and array indices are calculated and displayed with
correct syntax, constant char pointers are replaced with
appropriate quoted strings, etc.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">Propagating Local Data-types</emphasis></term>
<listitem>
<para>
The Decompiler infers the data-type of unlabeled variables
by propagating information from other sources throughout a function.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">Recovering Structure Definitions</emphasis></term>
<listitem>
<para>
The Decompiler can be used to create structures that match the usage
pattern of particular functions and variables, automatically discovering
component offsets and data-types.
</para>
</listitem>
</varlistentry>
</variablelist>
</informalexample>
</para>
</sect2>
</section>
</chapter>
<chapter id="DecompilerConcepts">
<title>Decompiler Concepts</title>
<section id="ConceptPcode">
<title>P-code</title>
<para>
P-code is Ghidra's Intermediate Representation (IR) language. When analyzing a function,
the Decompiler translates every machine instruction into p-code first and performs its
analysis directly on the operators and variables of the language. Output of the Decompiler
is also best understood in terms of p-code. This section presents the key concepts of
p-code. For a more detailed discussion see the document "P-Code Reference Manual."
</para>
<sect2 id="ConceptAddressSpace">
<title>Address Space</title>
<para>
P-code defines all data in terms of an address space. An <emphasis role="bold">address space</emphasis>
is defined simply as an indexed sequence of bytes that can be read and written by p-code operations.
For a specific byte, the unique index that labels it is called the byte's <emphasis role="bold">address</emphasis>.
Each address space has a:
<informalexample>
<itemizedlist mark='bullet'>
<listitem>
<emphasis role="bold">name</emphasis> - a formal name for the space
</listitem>
<listitem>
<emphasis role="bold">size</emphasis> - the maximum number of bytes that can be addressed
</listitem>
<listitem>
<emphasis role="bold">endianness</emphasis> - how groups of bytes are interpreted as integers
</listitem>
</itemizedlist>
</informalexample>
</para>
<para>
For a p-code model of a specific processor, all elements of the processor state (including RAM, registers,
flags, etc.) must be contained in some address space. The model will define multiple address spaces
to accomplish this, and beyond the raw translation of machine instructions to p-code, the Decompiler
can add additional spaces. Address space definitions that are common across many different processors include:
<informalexample>
<variablelist>
<?dbfo list-presentation="blocks"?>
<varlistentry>
<term><emphasis role="bold">ram</emphasis></term>
<listitem>
<para>
A space that models memory accessible via the processor's main data bus. Depending on
the architecture, different spaces might be substituted for <emphasis>ram</emphasis>,
such as separate <emphasis>code</emphasis> and <emphasis>data</emphasis> spaces.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">register</emphasis></term>
<listitem>
<para>
A space that models the processor's general purpose registers. Ghidra still uses
the standard names to refer to registers for the processor, but internally each register maps to a
specific address in this space.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">unique</emphasis></term>
<listitem>
<para>
A space dedicated to <emphasis>temporary</emphasis> registers.
It is used to hold intermediate values when modeling instruction behavior, and the Decompiler
uses it to allocate space for variables that don't directly correspond to the low level
processor state. The name <emphasis>unique</emphasis> is reserved for this purpose and
is present in all processor models.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">stack</emphasis></term>
<listitem>
<para>
A space that represents bytes explicitly indexed through a <emphasis>stack pointer</emphasis>.
This is an example of an address space added by the Decompiler beyond what the raw processor
model defines. The <emphasis>stack</emphasis> space is a logical construction representing the set of bytes a
single function might access through its stack pointer. Each stack address represents
the offset of a byte in some underlying space (usually <emphasis>ram</emphasis>) relative
to the initial value of the stack pointer upon entry to the function. The stack space is
always referenced in the context of a single function, and in this sense, each function
can be viewed as having its own distinct stack space.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">constant</emphasis></term>
<listitem>
<para>
A special space for encoding constants in p-code.
For complete generality, even constants that the processor might manipulate are
assigned to their own address space. For an address in the constant
space, the index itself represents the constant.
</para>
</listitem>
</varlistentry>
</variablelist>
</informalexample>
</para>
</sect2>
<sect2 id="ConceptVarnode">
<title>Varnodes</title>
<para>
A <emphasis role="bold">varnode</emphasis> is defined as a sequence of bytes in
an address space. It represents the storage for a single value (variable) being
acted on by the processor.
All manipulation of data by p-code operations occurs on varnodes.
A varnode can always be represented as the formal triple:
<informalexample>
<code>(address space,offset,size)</code>
</informalexample>
Both <emphasis>offset</emphasis> and <emphasis>size</emphasis> are integer values
specified in terms of bytes.
The first two elements, address space and offset, taken together represent the
<emphasis>address</emphasis> of the varnode.
</para>
<para>
Varnodes by themselves do not necessarily have a data-type associated with them.
The Decompiler ultimately assigns a formal data-type, but at the lowest level of p-code,
varnodes inherit one the building block data-types from the p-code operations that
act on them:
<informalexample>
<itemizedlist mark='bullet'>
<listitem>
<emphasis role="bold">Integer</emphasis>
</listitem>
<listitem>
<emphasis role="bold">Boolean</emphasis>
</listitem>
<listitem>
<emphasis role="bold">Floating Point</emphasis>
</listitem>
</itemizedlist>
</informalexample>
The integer data-type assumes a two's complement encoding in the endianness of the
address space containing the varnode. Similarly, the floating point data-type assumes
an IEEE 754 standard encoding. The precision of the integer or floating point value is
determined by the varnode's size. A boolean data-type assumes the varnode has a size
of 1 byte and takes either a value of 0, for <emphasis>false</emphasis>, or a value of
1 for <emphasis>true</emphasis>.
</para>
</sect2>
<sect2 id="ConceptPcodeOps">
<title>P-code Operations</title>
<para>
A <emphasis role="bold">p-code operation</emphasis> is defined as a formal operator,
labeled by its <emphasis>opcode</emphasis>, acting on 1 or more varnodes as input and
storing a result in at most 1 varnode. Each p-code operation is associated with an
address, which is usually the address of the machine instruction from which the p-code
operation was translated. As most instructions require more than one p-code operation
to fully model it, a separate 1-up counter is used to distinguish p-code operations
associated with the same address. Together the address and the counter are referred
to as the operation's <emphasis role="bold">sequence number</emphasis>.
</para>
<para>
The formal opcodes break up into categories similar to many programming languages.
<informalexample>
<table xml:id="ops.htmltable" width="90%" frame="box" rules="all">
<caption>P-code Operations</caption>
<col width="40%"/>
<col width="60%"/>
<thead>
<tr>
<td><emphasis role="bold">Category</emphasis></td>
<td><emphasis role="bold">Operations</emphasis></td>
</tr>
</thead>
<tbody>
<tr>
<td>Data Moving</td>
<td><code>COPY, LOAD, STORE</code></td>
</tr>
<tr>
<td>Integer Arithmetic</td>
<td><code>INT_ADD, INT_SUB,
INT_2COMP, INT_MULT, INT_DIV, INT_SDIV, INT_REM, INT_SREM</code></td>
</tr>
<tr>
<td>Integer Shifts</td>
<td><code>INT_LEFT, INT_RIGHT, INT_SRIGHT</code></td>
</tr>
<tr>
<td>Integer Comparison</td>
<td><code>INT_EQUAL, INT_NOTEQUAL, INT_SLESS, INT_SLESSEQUAL, INT_LESS, INT_LESSEQUAL</code></td>
</tr>
<tr>
<td>Logical</td>
<td><code>INT_NEGATE, INT_XOR, INT_AND, INT_OR, POPCOUNT</code></td>
</tr>
<tr>
<td>Boolean</td>
<td><code>BOOL_NEGATE, BOOL_XOR, BOOL_AND, BOOL_OR</code></td>
</tr>
<tr>
<td>Floating Point Arithmetic</td>
<td><code>FLOAT_ADD, FLOAT_SUB, FLOAT_MULT, FLOAT_DIV, FLOAT_NEG,
FLOAT_ABS, FLOAT_SQRT</code></td>
</tr>
<tr>
<td>Floating Point Comparison</td>
<td><code>FLOAT_EQUAL, FLOAT_NOTEQUAL, FLOAT_LESS, FLOAT_LESSEQUAL</code></td>
</tr>
<tr>
<td>Floating Point Conversion</td>
<td><code>INT2FLOAT, FLOAT2FLOAT, TRUNC, CEIL, FLOOR, ROUND</code></td>
</tr>
<tr>
<td>Branching</td>
<td><code>BRANCH, CBRANCH, BRANCHIND, CALL, CALLIND, RETURN</code></td>
</tr>
<tr>
<td>Extension/Truncation</td>
<td><code>INT_ZEXT, INT_SEXT, PIECE, SUBPIECE</code></td>
</tr>
<tr>
<td>Overflow Tests</td>
<td><code>INT_CARRY, INT_SCARRY, INT_SBORROW, FLOAT_NAN</code></td>
</tr>
<tr>
<td>Managed Code</td>
<td><code>CPOOLREF, NEW</code></td>
</tr>
</tbody>
</table>
</informalexample>
</para>
<sect3 id="ConceptOperatorTokens">
<title>Operator Tokens</title>
<para>
Most opcodes naturally correspond to a particular C operator token,
and in Decompiler output, many of the operator tokens displayed correspond
directly to a p-code operation present in the Decompiler's internal
representation. The biggest exception are the <emphasis>Branching</emphasis>
operations; the Decompiler uses standard high-level language control-flow
structures, like <emphasis>if/else</emphasis>, <emphasis>switch</emphasis>, and
<emphasis>do/while</emphasis> blocks, instead of the
low-level branching operations. But even here, there is some correspondence
between operations and keywords in the high-level language.
</para>
<para>
Operations in the <emphasis>Extension/Truncation</emphasis> and
<emphasis>Floating Point Conversion</emphasis> categories tend to be
represented as <emphasis>cast</emphasis> operations in the high-level language,
and so don't have an explicit operator token representing them. Many p-code
operations share the same operator token, such as the integer and floating-point
addition operations <emphasis role="bold">INT_ADD</emphasis> and
<emphasis role="bold">FLOAT_ADD</emphasis>. The high-level language distinguishes
between them via the underlying data-type of the variables.
</para>
<informalexample>
<table xml:id="ref.htmltable" width="90%" frame="box" rules="rows">
<col width="25%"/>
<col width="25%"/>
<col width="50%"/>
<thead>
<tr>
<td><emphasis role="bold">Name</emphasis></td>
<td><emphasis role="bold">Operator Token</emphasis></td>
<td><emphasis role="bold">Description</emphasis></td>
</tr>
</thead>
<tbody>
<tr>
<td>COPY</td>
<td><code>=</code></td>
<td>Copy one varnode into another.</td>
</tr>
<tr>
<td>LOAD</td>
<td><code>*</code> or <code>-></code></td>
<td>Dereference a pointer, or load a value from memory.</td>
</tr>
<tr>
<td>STORE</td>
<td><code>*</code> or <code>-></code></td>
<td>Store a value to memory, through a pointer.</td>
</tr>
<tr>
<td>BRANCH</td>
<td><code>goto</code></td>
<td>Branch execution to a specific address.</td>
</tr>
<tr>
<td>CBRANCH</td>
<td><code>if (...) goto</code></td>
<td>Branch execution to an address if the condition is true.</td>
</tr>
<tr>
<td>BRANCHIND</td>
<td><code>switch(...)</code></td>
<td>Branch execution to a computed address.</td>
</tr>
<tr>
<td>CALL</td>
<td><code>funcname(...)</code></td>
<td>Branch to a function, as a call.</td>
</tr>
<tr>
<td>CALLIND</td>
<td><code>(*funcptr)(...)</code></td>
<td>Branch through a pointer to a function, as a call.</td>
</tr>
<tr>
<td>RETURN</td>
<td><code>return</code></td>
<td>Return execution to the calling function.</td>
</tr>
<tr>
<td>PIECE</td>
<td><code>CONCAT</code></td>
<td>Concatenate two varnodes.</td>
</tr>
<tr>
<td>SUBPIECE</td>
<td><code>SUB</code></td>
<td>Extract a subset of bytes.</td>
</tr>
<tr>
<td>POPCOUNT</td>
<td><code>POPCOUNT</code></td>
<td>Count the 1 bits.</td>
</tr>
<tr>
<td>INT_EQUAL</td>
<td><code>==</code></td>
<td>True if input varnodes are equal.</td>
</tr>
<tr>
<td>INT_NOTEQUAL</td>
<td><code>!=</code></td>
<td>True if input varnodes are not equal.</td>
</tr>
<tr>
<td>INT_LESS</td>
<td><code><</code> or <code>></code></td>
<td>True if one varnode is less than the other as unsigned integers.</td>
</tr>
<tr>
<td>INT_SLESS</td>
<td><code><</code> or <code>></code></td>
<td>True if one varnode is less than the other as signed integers.</td>
</tr>
<tr>
<td>INT_LESSEQUAL</td>
<td><code><=</code> or <code>>=</code></td>
<td>True if one varnode is less than or equal to the other as unsigned integers.</td>
</tr>
<tr>
<td>INT_SLESSEQUAL</td>
<td><code><=</code> or <code>>=</code></td>
<td>True if one varnode is less than or equal to the other as signed integers.</td>
</tr>
<tr>
<td>INT_ZEXT</td>
<td><code>ZEXT</code></td>
<td>Zero extension.</td>
</tr>
<tr>
<td>INT_SEXT</td>
<td><code>SEXT</code></td>
<td>Signed extension.</td>
</tr>
<tr>
<td>INT_ADD</td>
<td><code>+</code></td>
<td>Add as integers.</td>
</tr>
<tr>
<td>INT_SUB</td>
<td><code>-</code></td>
<td>Subtract as integers.</td>
</tr>
<tr>
<td>INT_CARRY</td>
<td><code>CARRY</code></td>
<td>True if adding produces an unsigned carry.</td>
</tr>
<tr>
<td>INT_SCARRY</td>
<td><code>SCARRY</code></td>
<td>True if adding produces a signed carry.</td>
</tr>
<tr>
<td>INT_SBORROW</td>
<td><code>SBORROW</code></td>
<td>True if subtracting produces a signed borrow.</td>
</tr>
<tr>
<td>INT_2COMP</td>
<td><code>-</code></td>
<td>Two's complement.</td>
</tr>
<tr>
<td>INT_NEGATE</td>
<td><code>~</code></td>
<td>Bitwise negation.</td>
</tr>
<tr>
<td>INT_XOR</td>
<td><code>^</code></td>
<td>Bitwise exclusive-or.</td>
</tr>
<tr>
<td>INT_AND</td>
<td><code>&</code></td>
<td>Bitwise logical-and.</td>
</tr>
<tr>
<td>INT_OR</td>
<td><code>|</code></td>
<td>Bitwise logical-or.</td>
</tr>
<tr>
<td>INT_LEFT</td>
<td><code><<</code></td>
<td>Left shift.</td>
</tr>
<tr>
<td>INT_RIGHT</td>
<td><code>>></code></td>
<td>Unsigned (logical) right shift.</td>
</tr>
<tr>
<td>INT_SRIGHT</td>
<td><code>>></code></td>
<td>Signed (arithmetic) right shift.</td>
</tr>
<tr>
<td>INT_MULT</td>
<td><code>*</code></td>
<td>Integer multiplication.</td>
</tr>
<tr>
<td>INT_DIV</td>
<td><code>/</code></td>
<td>Unsigned integer division.</td>
</tr>
<tr>
<td>INT_REM</td>
<td><code>%</code></td>
<td>Unsigned remainder.</td>
</tr>
<tr>
<td>INT_SDIV</td>
<td><code>/</code></td>
<td>Signed division.</td>
</tr>
<tr>
<td>INT_SREM</td>
<td><code>%</code></td>
<td>Signed remainder.</td>
</tr>
<tr>
<td>BOOL_NEGATE</td>
<td><code>!</code></td>
<td>Boolean negation.</td>
</tr>
<tr>
<td>BOOL_XOR</td>
<td><code>^^</code></td>
<td>Boolean exclusive-or.</td>
</tr>
<tr>
<td>BOOL_AND</td>
<td><code>&&</code></td>
<td>Boolean logical-and.</td>
</tr>
<tr>
<td>BOOL_OR</td>
<td><code>||</code></td>
<td>Boolean logical-or.</td>
</tr>
<tr>
<td>FLOAT_EQUAL</td>
<td><code>==</code></td>
<td>True if inputs are equal as floating-point numbers.</td>
</tr>
<tr>
<td>FLOAT_NOTEQUAL</td>
<td><code>!=</code></td>
<td>True if inputs are not equal as floating-point numbers.</td>
</tr>
<tr>
<td>FLOAT_LESS</td>
<td><code><</code> or <code>></code></td>
<td>True if one input is less than the other as floating-point numbers.</td>
</tr>
<tr>
<td>FLOAT_LESSEQUAL</td>
<td><code><=</code> or <code>>=</code></td>
<td>True if one input is less than or equal to the other as floating-point numbers.</td>
</tr>
<tr>
<td>FLOAT_ADD</td>
<td><code>+</code></td>
<td>Add as floating-point numbers.</td>
</tr>
<tr>
<td>FLOAT_SUB</td>
<td><code>-</code></td>
<td>Subtract as floating-point numbers.</td>
</tr>
<tr>
<td>FLOAT_MULT</td>
<td><code>*</code></td>
<td>Multiply as floating-point numbers.</td>
</tr>
<tr>
<td>FLOAT_DIV</td>
<td><code>/</code></td>
<td>Divide as floating-point numbers.</td>
</tr>
<tr>
<td>FLOAT_NEG</td>
<td><code>-</code></td>
<td>Negate a floating-point number.</td>
</tr>
<tr>
<td>FLOAT_ABS</td>
<td><code>ABS</code></td>
<td>Absolute value of a floating-point number.</td>
</tr>
<tr>
<td>FLOAT_SQRT</td>
<td><code>SQRT</code></td>
<td>Square root of a floating-point number.</td>
</tr>
<tr>
<td>FLOAT_CEIL</td>
<td><code>CEIL</code></td>
<td>Ceiling function.</td>
</tr>
<tr>
<td>FLOAT_FLOOR</td>
<td><code>FLOOR</code></td>
<td>Floor function.</td>
</tr>
<tr>
<td>FLOAT_ROUND</td>
<td><code>ROUND</code></td>
<td>Nearest integral value.</td>
</tr>
<tr>
<td>FLOAT_NAN</td>
<td><code>NAN</code></td>
<td>True if input is not a valid floating-point number (NaN).</td>
</tr>
<tr>
<td>INT2FLOAT</td>
<td><code><na></code></td>
<td>Convert integer to floating-point.</td>
</tr>
<tr>
<td>FLOAT2FLOAT</td>
<td><code><na></code></td>
<td>Convert between different floating-point precisions.</td>
</tr>
<tr>
<td>TRUNC</td>
<td><code><na></code></td>
<td>Convert floating-point to integer.</td>
</tr>
<tr>
<td>CPOOLREF</td>
<td><code><na></code></td>
<td>Obtain constant pool value.</td>
</tr>
<tr>
<td>NEW</td>
<td><code>new</code></td>
<td>Allocate an object or an array of objects.</td>
</tr>
<tr>
<td>MULTIEQUAL</td>
<td><code><na></code></td>
<td>Compiler phi-node: merge values from multiple control-flow paths.</td>
</tr>
<tr>
<td>INDIRECT</td>
<td><code><na></code></td>
<td>Indirect effect on a varnode.</td>
</tr>
<tr>
<td>CAST</td>
<td><code><na></code></td>
<td>Copy a value, changing its data-type.</td>
</tr>
<tr>
<td>PTRADD</td>
<td><code>+</code></td>
<td>Add an offset to a pointer.</td>
</tr>
<tr>
<td>PTRSUB</td>
<td><code>.</code> or <code>-></code></td>
<td>Dereference a subfield from a pointer.</td>
</tr>
<tr>
<td>INSERT</td>
<td><code><na></code></td>
<td>Insert a bit-range.</td>
</tr>
<tr>
<td>EXTRACT</td>
<td><code><na></code></td>
<td>Extract a bit-range.</td>
</tr>
</tbody>
</table>
</informalexample>
</sect3>
<sect3 id="ConceptControlFlow">
<title>P-code Control Flow</title>
<para>
P-code has natural <emphasis role="bold">control flow</emphasis>, with the subtlety that flow
happens both within and across machine instructions. Most p-code operators have
<emphasis role="bold">fall-through</emphasis> semantics, meaning that flow moves to the
next operator in the sequence associated with the instruction, or, if the operator is the
last in the sequence, flow moves to the first operator in the p-code associated with the next instruction.
The p-code operators with <emphasis role="bold">branching</emphasis> semantics, such as
CBRANCH and BRANCH, can jump to a target operator which is internal to the current instruction, or they can
jump to the first p-code operator corresponding to a new instruction at a different address.
</para>
<para>
Ghidra labels a machine instruction with one of the following <emphasis role="bold">Flow Types</emphasis> that describe
its overall control flow. The Flow Type is derived directly from the control flow of the p-code for the instruction,
with the basic types corresponding directly with a specific branching p-code operator.
<informalexample>
<itemizedlist mark='none'>
<listitem><emphasis role="bold">FALL_THROUGH</emphasis></listitem>
<listitem><emphasis role="bold">UNCONDITIONAL_CALL</emphasis> - CALL</listitem>
<listitem><emphasis role="bold">UNCONDITIONAL_JUMP</emphasis> - BRANCH</listitem>
<listitem><emphasis role="bold">CONDITIONAL_JUMP</emphasis> - CBRANCH</listitem>
<listitem><emphasis role="bold">COMPUTED_JUMP</emphasis> - BRANCHIND</listitem>
<listitem><emphasis role="bold">COMPUTED_CALL</emphasis> - CALLIND</listitem>
<listitem><emphasis role="bold">TERMINATOR</emphasis> - RETURN</listitem>
</itemizedlist>
</informalexample>
Other Flow Types occur due to a combination of multiple p-code branching operators within the same instruction.
<informalexample>
<itemizedlist mark='none'>
<listitem><emphasis role="bold">CONDITIONAL_CALL</emphasis> - CALL with CBRANCH</listitem>
<listitem><emphasis role="bold">CONDITIONAL_TERMINATOR</emphasis> - RETURN with CBRANCH</listitem>
<listitem><emphasis role="bold">COMPUTED_CALL_TERMINATOR</emphasis> - CALLIND with RETURN</listitem>
<listitem><emphasis role="bold">CONDITIONAL_COMPUTED_JUMP</emphasis> - CBRANCH with BRANCHIND</listitem>
<listitem><emphasis role="bold">CONDITIONAL_COMPUTED_CALL</emphasis> - CBRANCH with CALLIND</listitem>
<listitem><emphasis role="bold">JUMP_TERMINATOR</emphasis> - BRANCH with RETURN</listitem>
</itemizedlist>
</informalexample>
</para>
</sect3>
<sect3 id="ConceptCallother">
<title>User-defined P-code Operations - CALLOTHER</title>
<para>
P-code allows for additional, processor specific, operations referred to
as <emphasis>user-defined</emphasis> or CALLOTHER operations.
These may be defined as part of a Ghidra's specification for the processor and
are typically used as placeholders for what is otherwise unmodeled processor behavior.
Each CALLOTHER must have a unique name, and as a p-code operation, it still takes
varnode inputs and may produce a varnode output. But the exact affect of the operation is
not specified.
</para>
<para>
The Decompiler treats a CALLOTHER operation as a black box. It will keep track of data
flowing into and out of the operation but won't simplify or transform it. In Decompiler
output, a CALLOTHER is usually displayed using its unique name, with functional syntax
showing its inputs and output.
</para>
<para>
Ghidra or a user can provide the behavior details for a named CALLOTHER operation. The
details are provided as a sequence of p-code operations, referred to as a
<emphasis role="bold">Callother-Fixup</emphasis>, which is substituted for the
CALLOTHER operation during decompilation, or by other Analyzers that use p-code.
Callother-Fixups are applied by Ghidra for specific processor or compiler variants,
and a user can choose to apply them to an individual Program (see <xref linkend="ExtensionOptions"/>).
</para>
</sect3>
<sect3 id="ConceptInternalFunctions">
<title>Internal Decompiler Functions</title>
<para>
Certain p-code operations can show up in Decompiler output that cannot be represented
as either an operator token, a cast operation, or other depiction that is natural to
the language. The Decompiler generally tries to eliminate these, but this isn't always
possible. The Decompiler resorts to a functional syntax for these kinds
of p-code operations, displaying them as if they were built-in functions for the language.
</para>
<informalexample>
<variablelist>
<?dbfo list-presentation="blocks"?>
<varlistentry>
<term><code>SUB41(x,c)</code> - Truncation operation - SUBPIECE</term>
<listitem>
<itemizedlist mark='bullet' spacing='compact'>
<listitem>The digit '4' indicates the size of the input operand 'x' in bytes.</listitem>
<listitem>The digit '1' indicates the size of the output value in bytes.</listitem>
<listitem>The parameter 'x' is the value being truncated.</listitem>
<listitem>The parameter 'c' is the number of least significant bytes being truncated.</listitem>
</itemizedlist>
<programlisting>
SUB42(0xaabbccdd,1) = 0xbbcc
</programlisting>
<para>
Extract a contiguous subset of the bytes from 'x'.
When 'c' is 0, the operation is a simple integer truncation.
</para>
<para>
<itemizedlist mark='none'>
<listitem>
<code>SUB41(x,0)</code>
truncates from a 4-byte integer to a 1-byte (<emphasis role="bold">char</emphasis>
or <emphasis role="bold">byte</emphasis>) integer.
</listitem>
<listitem>
<code>SUB42(x,0)</code>
truncates from a 4-byte integer to a 2-byte (<emphasis role="bold">short</emphasis>) integer.
</listitem>
<listitem>
<code>SUB84(x,4)</code> extracts the high 4 bytes from the 8 byte integer.
</listitem>
</itemizedlist>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><code>CONCAT31(x,y)</code> - Concatenation operator - PIECE</term>
<listitem>
<itemizedlist mark='bullet' spacing='compact'>
<listitem>The digit '3' indicates the size of the input operand 'x' in bytes.</listitem>
<listitem>The digit '1' indicates the size of the input operand 'y' in bytes.</listitem>
<listitem>The parameters 'x' and 'y' hold the values being concatenated.</listitem>
</itemizedlist>
<programlisting>
CONCAT31(0xaabbcc,0xdd) = 0xaabbccdd
</programlisting>
<para>
Concatenate the bytes in 'x' with the bytes in 'y'. 'x' becomes the most significant
bytes, and 'y' the least significant bytes, in the result.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><code>ZEXT14(x)</code> - Zero-extension operator - INT_ZEXT</term>
<listitem>
<itemizedlist mark='bullet' spacing='compact'>
<listitem>The digit '1' indicates the size of the input operand 'x' in bytes.</listitem>
<listitem>The digit '4' indicates the size of the output in bytes.</listitem>
</itemizedlist>
<programlisting>
ZEXT24(0xaabb) = 0x0000aabb
</programlisting>
<para>
Extend the operand 'x' to a larger size by appending zero bytes, which become the most
significant bytes of the result.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><code>SEXT14(x)</code> - Sign-extension operator - INT_SEXT</term>
<listitem>
<itemizedlist mark='bullet' spacing='compact'>
<listitem>The digit '1' indicates the size of the input operand 'x' in bytes.</listitem>
<listitem>The digit '4' indicates the size of the output in bytes.</listitem>
</itemizedlist>
<programlisting>
SEXT48(0xaabbccdd) = 0xffffffffaabbccdd
</programlisting>
<para>
Extend the operand 'x' to a larger size by duplicating the <emphasis>sign</emphasis>
bit of 'x' into the most significant bytes of the result.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><code>SBORROW4(x,y)</code> - Test for signed borrow operator - INT_SBORROW</term>
<listitem>
<itemizedlist mark='bullet' spacing='compact'>
<listitem>The digit '4' indicates the size of both input operands 'x' and 'y' in bytes.</listitem>
</itemizedlist>
<para>
Return <emphasis>true</emphasis> if there is an arithmetic overflow when subtracting 'y' from 'x'
as signed integers.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><code>CARRY4(x,y)</code> - Test for unsigned overflow operator - INT_CARRY</term>
<listitem>
<itemizedlist mark='bullet' spacing='compact'>
<listitem>The digit '4' indicates the size of both input operands 'x' and 'y' in bytes.</listitem>
</itemizedlist>
<para>
Return <emphasis>true</emphasis> if there is an arithmetic overflow when adding 'x' and 'y'
as unsigned integers.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><code>SCARRY4(x,y)</code> - Test for signed overflow operator - INT_SCARRY</term>
<listitem>
<itemizedlist mark='bullet' spacing='compact'>
<listitem>The digit '4' indicates the size of both input operands 'x' and 'y' in bytes.</listitem>
</itemizedlist>
<para>
Return <emphasis>true</emphasis> if there is an arithmetic overflow when adding 'x' and 'y'
as signed integers.
</para>
</listitem>
</varlistentry>
</variablelist>
</informalexample>
</sect3>
</sect2>
</section>
<section id="ConceptHighFunction">
<title>The HighFunction</title>
<para>
A <emphasis role="bold">HighFunction</emphasis> is the collection of specific information
produced by the Decompiler about a function, referring to the root class in the Ghidra
source which holds this information.
The HighFunction is made up of the following explicit objects:
<informalexample>
<itemizedlist mark='bullet'>
<listitem>
A <emphasis role="bold">control-flow</emphasis> representation of the function
in terms of <emphasis>basic blocks</emphasis>.
</listitem>
<listitem>
A <emphasis role="bold">data-flow</emphasis> representation of the function
in terms of <emphasis>varnodes</emphasis> and <emphasis>p-code operations</emphasis>.
</listitem>
<listitem>
A <emphasis role="bold">symbol-table</emphasis> of variables accessed by the function.
</listitem>
</itemizedlist>
</informalexample>
</para>
<para>
The Decompiler's output provides a standalone view of the function which is distinct
from any annotations about the function that are present in the Program database
and displayed in the Listing (although the output may be informed by these annotations).
The terms <emphasis>HighFunction</emphasis>, <emphasis>HighVariable</emphasis>, and
<emphasis>HighSymbol</emphasis> refer to this Decompiler specific view of the function.
</para>
<sect2 id="ConceptHighSymbol">
<title>HighSymbol</title>
<para>
A <emphasis role="bold">HighSymbol</emphasis> is one of the explicit symbols recovered by the
Decompiler. It is made up of a name and data-type and can describe either:
<informalexample>
<itemizedlist mark='none'>
<listitem>
a formal <emphasis role="bold">parameter</emphasis> of the function,
</listitem>
<listitem>
a <emphasis role="bold">local variable</emphasis> of the function, or
</listitem>
<listitem>
a <emphasis role="bold">global variable</emphasis> accessed by the function.
</listitem>
</itemizedlist>
</informalexample>
</para>
<para>
An important aspect of HighSymbols is that they are distinct from
the standard Ghidra symbols stored in the Program database and are part of
the Decompiler's separate view of the function. When the Decompiler displays
declarations for symbols in its output for instance, it is displaying
HighSymbols, which may not directly match up with database symbols.
The Decompiler is generally
<emphasis>informed</emphasis> by annotations in the database and may
copy specific symbols from the database into its view, but it is
generally free to invent new symbols discovered during its analysis.
</para>
<para>
Various actions within Ghidra allow the user to <emphasis>commit</emphasis>
specific HighSymbols to the database as a permanent annotation, but this
does not happen by default.
</para>
</sect2>
<sect2 id="ConceptVarnodeSSA">
<title>Varnodes in the Decompiler</title>
<para>
Varnodes are the central <emphasis>variable</emphasis> concept for the Decompiler.
They form the individual nodes in the Decompiler's data-flow representation
of functions and are used during all stages of analysis. During the initial stages
of analysis, varnodes simply represent specific storage locations that are accessed
in sequence by individual p-code operations. The Decompiler immediately converts
the p-code into a graph-based data-flow representation, called Static Single
Assignment (SSA) form. In this form, the varnodes take on some additional attributes.
</para>
<para>
In SSA form, each write of an operation to a storage location defines a new varnode.
Write operations at different points in the code to the same storage location, still
produce different varnodes. In this context, each varnode has a <emphasis>lifetime</emphasis>
or <emphasis>scope</emphasis> within the function. The scope starts at:
<informalexample>
<itemizedlist mark='none'>
<listitem>
<para>
The <emphasis role="bold">defining</emphasis> p-code operation which has the
varnode as its output. <emphasis>Or</emphasis>
</para>
</listitem>
<listitem>
<para>
The beginning of the function, if the varnode is an <emphasis role="bold">input</emphasis>
to the function.
</para>
</listitem>
</itemizedlist>
</informalexample>
The scope extends via control flow to each p-code operation that <emphasis>reads</emphasis> the
specific varnode as an operand. The value of the varnode between the defining p-code operation
and the reading operations does not change. The scope of a varnode can be thought of as a set
of addresses within the function's body connected by control flow. The address of the defining
p-code operation is referred to as the varnode's <emphasis role="bold">first use point</emphasis>
or <emphasis role="bold">first use offset</emphasis>.
</para>
<para>
In the Decompiler output for a specific high-level language like C or Java,
a varnode still has a <emphasis>scope</emphasis> and represents a variable
in the high-level language only across this connected region of the code.
A set of varnodes, with disjoint scopes, provides a complete
description of a high-level variable that can be written to at more than one point
in the function.
</para>
</sect2>
<sect2 id="ConceptHighVariable">
<title>HighVariable</title>
<para>
A <emphasis role="bold">HighVariable</emphasis> is a set varnodes that, taken
together, represent the storage of an entire variable in the high-level language
being output by the Decompiler. Each varnode describes where the variable's
value is stored across some section of code.
</para>
<para>
There is generally a one-to-one correspondence between HighVariables and
HighSymbols. HighVariables can be thought of as the detailed storage description
of the high-level variable, while the HighSymbol provides its name and data-type.
However, there are some technical caveats to this correspondence to keep in mind.
</para>
<para>
A HighVariable always describes <emphasis>explicit</emphasis> manipulation of
data by instructions in the function. In some cases, a HighVariable may only describe part
of the storage for a HighSymbol. Particularly for structured or composite data-types, a
function may operate on different parts of the variable at different points of the code,
so a HighVariable may only encompass one field of the structure.
</para>
<para>
A symbol may be referenced in a function, but the symbol's value may not be explicitly
manipulated. Constant pointers may refer to variables either
on the stack or in main memory, but the variable's value is neither read nor written
within the function. In this case, the HighSymbol exists, but there
is no corresponding HighVariable.
</para>
<sect3 id="ConceptMerging">
<title>Merging</title>
<para>
<emphasis role="bold">Merging</emphasis> is the part of the analysis process where
the Decompiler decides what varnodes get grouped together to create the final
HighVariables in the output. Each varnode's scope (see the discussion in
<xref linkend="ConceptVarnodeSSA"/>) provides the fundamental restriction on this process.
Two varnodes cannot be merged if their scopes intersect. But this leaves a lot of
leeway in what varnodes <emphasis>can</emphasis> be merged.
</para>
<para>
Certain varnodes must be merged; if they use the same storage but in different
control-flow paths that come together, for instance, or if it is explicitly
known that the varnodes must represent the same variable. This is referred
to as <emphasis role="bold">forced merging</emphasis>.
</para>
<para>
The Decompiler may also merge varnodes that could just as easily exist as separate
variables. This is called <emphasis role="bold">speculative merging</emphasis>.
In addition to the intersection condition on varnode scopes, the Decompiler only
speculatively merges variables that share the same data-type. Beyond this, the Decompiler
prioritizes variable pairs that are read and written within the same instruction and
then pairs that are <emphasis>near</emphasis> each other in the control flow of the function.
To a limited extent, users are able to control this kind of merging
(see <xref linkend="ActionIsolate"/>).
</para>
</sect3>
</sect2>
<sect2 id="ConceptPrototypeModel">
<title>Prototype Model</title>
<para>
Functions in high-level languages manipulate symbols like parameters and return values that
are implicitly stored in a way that doesn't collide with other functions and variables. To
actually map these symbols to physical registers and memory locations, compilers establish a
<emphasis>calling convention</emphasis> for the function.
Loosely, this is a set of memory resources, whether it is registers or stack locations,
and a procedure for sequentially assigning resources to parameters based on their properties.
A <emphasis role="bold">prototype model</emphasis> is the formal object in Ghidra that represents
a calling convention and holds its specific rules and resource details.
</para>
<para>
Prototype models are architecture-specific, and depending on the compiler, a single Program may make
use of multiple models. Subsequently, each distinct model has a name like <emphasis role="bold">__stdcall</emphasis> or
<emphasis role="bold">__thiscall</emphasis>. The Decompiler makes use of the prototype model, as assigned to the function by the user or
discovered in some other way, when performing its analysis of parameters.
It is possible for users to extend the set of prototype models available to a Program
(see <xref linkend="ExtensionOptions"/>).
</para>
<para>
A prototype model is typically used as a whole and is assigned by name to individual functions. But some of
the sub-concepts of the model may be relevant to reverse engineers. Concepts that a prototype
model encapsulates include:
</para>
<sect3 id="ConceptPrototypeStorage">
<title>Incoming and Outgoing Storage Locations</title>
<para>
A formal input parameter is always assigned a specific memory location to hold its value coming into the function.
The storage location can be a register, a stack location, or other memory location. The storage
location may be reused later by other variables in the function; only the incoming value stored there is guaranteed
to be that of input parameter.
</para>
<para>
If the parameter
is stored on the stack, the storage location is viewed as a constant offset in the <emphasis role="bold">stack</emphasis>
space, where the offset is relative to the incoming value of <emphasis>stack pointer</emphasis>
(see the discussion in <xref linkend="ConceptAddressSpace"/>).
</para>
<para>
The <emphasis>return value</emphasis> for the function, unless it is passed back on the stack, is also stored at a single
memory location. It is guaranteed to be at that location only at points where the function is exited. There may be multiple exit
points, but they all share the same return value storage location. For return values passed back on the stack, compilers
generally implement a special input register to hold the location where the value will be stored. See the
discussion of <xref linkend="ConceptAutoParameters"/> and the <emphasis role="bold">__return_storage_ptr__</emphasis> below.
</para>
</sect3>
<sect3 id="ConceptAutoParameters">
<title>Auto-Parameters</title>
<para>
Compiled binaries may pass values as parameters between functions that aren't in the formal
list of parameters as defined by the original source code for the program. These are referred to
as <emphasis role="bold">auto-parameters</emphasis> or sometimes <emphasis role="bold">hidden</emphasis>
parameters within the documentation. If the prototype model requires it, Ghidra will automatically
create an auto-parameter for a function to honor a user's request for a specific formal signature.
See <link xlink:href="help/topics/FunctionPlugin/Variables.htm#Edit_Function">Function Editor Dialog</link>.
Because reverse engineers need to see them, the
Decompiler will generally display auto-parameters explicitly in function prototypes as part of its output, even though
they would not be present in the original source.
Ghidra explicitly defines two auto-parameters:
<informalexample>
<variablelist>
<?dbfo list-presentation="blocks"?>
<varlistentry>
<term><emphasis role="bold">this</emphasis></term>
<listitem>
<para>
Within Object Oriented languages, a function defined as a class <emphasis>method</emphasis>
often has a <emphasis role="bold">this</emphasis> parameter pointing to an instantiation of the
class' structure data-type. Within Ghidra, functions with the <emphasis role="bold">__thiscall</emphasis>
calling convention are automatically assigned a <emphasis role="bold">this</emphasis> parameter.
If the function is part of a class namespace and the class has an associated structure, the
<emphasis role="bold">this</emphasis> parameter will be a pointer to the structure, otherwise
it will be a pointer to the <emphasis role="bold">void</emphasis> data-type.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">__return_storage_ptr__</emphasis></term>
<listitem>
<para>
Most calling conventions allow the value returned by a function, if it is large enough, to be passed back
on the stack instead of in a register. This is usually implemented by having the calling function
pass an additional <emphasis>input</emphasis> parameter that holds a pointer to the location on
the stack where the return value should be stored. Ghidra labels this special parameter as
<emphasis role="bold">__return_storage_ptr__</emphasis>, which will be a pointer to the
data-type of the return value.
</para>
</listitem>
</varlistentry>
</variablelist>
</informalexample>
</para>
</sect3>
<sect3 id="ConceptPrototypeUnaffected">
<title>Unaffected</title>
<para>
Prototype models can specify a set of <emphasis role="bold">unaffected</emphasis> memory locations,
whose value must be <emphasis>preserved</emphasis> across the function. I.e. each location
must hold the same value at a function's exit that it held coming into the function.
These encompass a calling convention's <emphasis>saved registers</emphasis>, where a calling function
can store values it doesn't want to change unexpectedly, but also may include other registers that are
known not to change, like the stack pointer.
The Decompiler uses the information to determine which locations can be safely propagated across
a called function.
</para>
</sect3>
<sect3 id="ConceptPrototypeKilledByCall">
<title>Killed by Call</title>
<para>
In contrast to <emphasis>unaffected</emphasis> memory locations, a prototype model may specify
<emphasis role="bold">killed by call</emphasis> locations that are guaranteed <emphasis>not</emphasis>
to be used to hold a value across the function.
</para>
</sect3>
</sect2>
</section>
<section id="ConceptSpecification">
<title>SLEIGH Specification Files</title>
<para>
SLEIGH is Ghidra's specification language for describing processor instructions.
Specification files are read in for a Program, and once configured, Ghidra's SLEIGH engine can:
<informalexample>
<itemizedlist mark='bullet' spacing='compact'>
<listitem>
Disassemble machine instructions from the underlying bytes and
</listitem>
<listitem>
Produce the raw p-code consumed by the Decompiler and other analyzers.
</listitem>
</itemizedlist>
</informalexample>
</para>
<para>
Specification files are selected based on the <emphasis>Language Id</emphasis>
assigned to the Program at the time it is imported into Ghidra
(see <link xlink:href="help/topics/ImporterPlugin/importer.htm">Import Program</link>).
<informalexample>
<itemizedlist mark='none' spacing='compact'>
<listitem><code>x86:LE:32:default:windows</code></listitem>
<listitem><code>AARCH64:LE:64:default:v8A:default</code></listitem>
<listitem><code>MIPS:BE:32:micro:default</code></listitem>
</itemizedlist>
</informalexample>
A <emphasis role="bold">Language Id</emphasis> is a label with these 5 formal fields, separated
by a ':' character:
<informalexample>
<itemizedlist spacing='compact'>
<listitem>Processor family</listitem>
<listitem>Endianness</listitem>
<listitem>Size of the address bus</listitem>
<listitem>Processor variant</listitem>
<listitem>Compiler producing the Program</listitem>
</itemizedlist>
</informalexample>
A field with the value <emphasis role="bold">default</emphasis> indicates either the preferred processor variant or the preferred compiler.
</para>
<para>
Within the Ghidra installation, specification files are stored based on the overarching
processor family, such as <emphasis role="bold">MIPS</emphasis> or
<emphasis role="bold">x86</emphasis>. For a specific family, files are located under
<informalexample>
<code><Root>/Ghidra/Processors/<Family>/data/languages</code>
</informalexample>
where <code><Root></code> represents the root directory of the Ghidra installation and
<code><Family></code> is the processor family.
</para>
<para>
There are several types of specification files that are distinguishable by their suffix.
These include:
<informalexample>
<variablelist>
<?dbfo list-presentation="blocks"?>
<varlistentry>
<term><emphasis role="bold">SLEIGH files</emphasis> - *.slaspec or *.sinc</term>
<listitem>
<para>
These are the human readable SLEIGH language files. A single specification is
rooted in one of the <code>*.slaspec</code> files, which may recursively include
one or more <code>*.sinc</code> files. The format of these files is described
in the document "SLEIGH: A Language for Rapid Processor Specification."
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">Compiled SLEIGH files</emphasis> - *.sla</term>
<listitem>
<para>
This is a compiled form of a single SLEIGH specification. It is produced
automatically by Ghidra from the corresponding <code>*.slaspec</code>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">Compiler specification files</emphasis> - *.cspec</term>
<listitem>
<para>
These files contain configuration for a specific compiler. Analysis of Programs whose
executable content was produced using this compiler benefits from this information.
The file is an XML document with tags describing details of data organization and
other conventions used by the compiler. In particular, the compiler specification
contains tags:
</para>
<para>
<itemizedlist mark='none' spacing='compact'>
<listitem><prototype> - describing a specific calling convention</listitem>
<listitem><callfixup> - describing a Call-fixup</listitem>
<listitem><callotherfixup> - describing a Callother-fixup</listitem>
</itemizedlist>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">Processor specification files</emphasis> - *.pspec</term>
<listitem>
<para>
These files contain configuration information that is specific to a particular
processor variant.
</para>
</listitem>
</varlistentry>
</variablelist>
</informalexample>
</para>
<sect2 id="ConceptModifySpec">
<title>Modifying Specification Files</title>
<para>
Changing any of the specification files described here is not recommended.
To make additions to either the <emphasis>compiler specification</emphasis>
or the <emphasis>processor specification</emphasis> files, see
<xref linkend="ExtensionOptions"/>, which describes a safe and portable way
to add specific elements.
</para>
<warning>
Making modifications to specification files within a Ghidra installation is possible,
but any analysis results obtained will likely not be portable to other installations.
In particular, saving a Program from a modified Ghidra and then reopening it using
an unmodified installation may corrupt the Program database.
</warning>
<para>
When Ghidra starts, it checks for changes to <code>*.slaspec</code>
and <code>*.sinc</code> files and will rebuild the corresponding
<code>*.sla</code> file automatically. Also, specification files are read again when
Ghidra restarts. So analysts can and do make changes to these files.
However they need to be prepared to view any results as temporary and
should backup their installation and specific Programs being analyzed.
</para>
</sect2>
</section>
</chapter>
<chapter id="DecompilerAnnotations">
<title>Program Annotations Affecting the Decompiler</title>
<section id="AnnoteFunctionBody">
<title>Machine Instructions</title>
<para>
Individual <emphasis role="bold">machine instructions</emphasis>
make up the biggest source of information when the
Decompiler analyzes a function. Instructions are translated from their
processor-specific form into Ghidra's IR language (see <xref linkend="ConceptPcode"/>),
which provides both the control-flow behavior of the instruction and the detailed
semantics describing how the processor and memory state are affected. The translation is controlled by
the underlying processor model and, except in limited circumstances, cannot be directly altered
from the tool. Flow Overrides (see below) can change how certain control flow is translated
and, depending on the processor, how context registers affect p-code (see <xref linkend="AnnoteContextRegister"/>).
</para>
<para>
Outside of the tool, users <emphasis>can</emphasis> modify the model specification itself.
See the document "SLEIGH: A Language for Rapid Processor Specification."
</para>
<para>
Decompiling a function starts by analyzing the control flow of machine instructions.
Control flow is traced from the first instruction, through additional instructions depending
on their flow semantics (see <xref linkend="ConceptControlFlow"/>). All paths are traced through instructions with
any form of <emphasis>fall-through</emphasis> or <emphasis>jump</emphasis>
semantics until an instruction with <emphasis>terminator</emphasis> semantics is
reached, which is usually a formal <emphasis>return</emphasis> (return from subroutine) instruction.
Flow is not traced into called functions, in this situation. Instructions
with <emphasis>call</emphasis> semantics are treated only as if they fall through.
</para>
<para>
An <emphasis role="bold">entry point</emphasis> is the address of the instruction first
executed when the function is called.
</para>
<para>
A <emphasis role="bold">function body</emphasis> is the set of addresses reached by control-flow
analysis and the machine instructions at those addresses.
</para>
<sect2 id="AnnoteEntryPoint">
<title>Entry Point</title>
<para>
The <emphasis>entry point</emphasis> address for a function plays a pivotal role for
analysis using the Decompiler. Ghidra generally associates
a formal <emphasis>Function Symbol</emphasis> and an underlying
<emphasis>Function</emphasis> object at this address, which are the key elements that
need to be present to trigger decompilation
(see <link xlink:href="help/topics/FunctionPlugin/Functions.htm">Functions</link>).
The Function object stores the function body, parameters, local variables, and
other information critical to the decompilation process.
</para>
<para>
Function Symbols and Function objects are generally created automatically by a Ghidra
analyzer when initially importing a binary executable and running Auto Analysis.
If necessary, however, a user can manually create a Function object from a Listing window
by using the <emphasis>Create Function</emphasis> command (pressing the 'F' key), when the cursor
is placed on the function's entry point
(see <link xlink:href="help/topics/FunctionPlugin/Functions.htm#Create_Function">Create Function</link>).
</para>
</sect2>
<sect2 id="AnnoteFormalFunctionBody">
<title>Formal Function Body</title>
<para>
When a function is created, Ghidra stores its function body as a set of addresses in the
Program database. This <emphasis>formal</emphasis> function body delineates the function
from all the other kinds of data within the Program and lets Ghidra immediately link addresses
in the middle of the function to the entry point and the Function object. Decompiler windows
in particular use the formal function body to know which function to decompile in response
to a navigation event to an arbitrary address.
</para>
<warning>
The Decompiler does <emphasis>not</emphasis> use the formal function body when it computes
control flow; it recomputes its own idea of the function body starting from the entry point
it is handed. If the formal function body was created manually, using a selection for instance,
or in other extreme circumstances, the Decompiler's view of the function body may not match
the formal view. This can lead to confusing behavior, where clicking in a Decompiler window
may unexpectedly navigate the window away from the function.
</warning>
</sect2>
<sect2 id="AnnoteFlowOverride">
<title>Flow Overrides</title>
<para>
Control-flow behavior for a machine instruction is generally determined by its underlying
p-code (see <xref linkend="ConceptControlFlow"/>), but this can be changed by applying a Flow Override.
A <emphasis role="bold">Flow Override</emphasis> maintains the overall semantics of a branching instruction
but changes how the branch is interpreted. For instance, a <code>JMP</code> instruction, which traditionally
represents a branch within a single function, can be overridden to represent a call to a new function.
Flow Overrides are applied by Analyzers or manually by the user.
</para>
<para>
The Decompiler automatically incorporates any relevant Flow Overrides into its
analysis of a function. This can have a significant impact on results. The
types of possible Flow Overrides include:
<informalexample>
<variablelist>
<?dbfo list-presentation="blocks"?>
<varlistentry>
<term><emphasis role="bold">BRANCH Override</emphasis></term>
<listitem>
<para>
Treats the primary <emphasis>CALL</emphasis> or <emphasis>RETURN</emphasis>
behavior of the instruction as if it were a <emphasis>BRANCH</emphasis>
within the function. For <emphasis>CALL</emphasis> instructions,
the call target becomes the branch destination,
and the instruction is no longer assumed
to fall through. <emphasis>RETURN</emphasis> instructions become an
indirect branch, and the Decompiler will attempt to recover branch
destinations using <emphasis>switch</emphasis> analysis.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">CALL Override</emphasis></term>
<listitem>
<para>
Treats the primary <emphasis>BRANCH</emphasis> or <emphasis>RETURN</emphasis>
behavior of the instruction as if it were a <emphasis>CALL</emphasis>.
A <emphasis>BRANCH</emphasis> becomes a fall through instruction, and the destination address becomes
the call target, which may no longer be considered part of the function. The computed
address for an indirect <emphasis>BRANCH</emphasis> or <emphasis>RETURN</emphasis> instruction becomes
the target address of an indirect <emphasis>CALL</emphasis>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">CALL_RETURN Override</emphasis></term>
<listitem>
<para>
Treats the primary <emphasis>BRANCH</emphasis> or <emphasis>RETURN</emphasis>
behavior of the instruction as if it executed a <emphasis>CALL</emphasis> followed
by a <emphasis>RETURN</emphasis> operation.
The destination address of a <emphasis>BRANCH</emphasis> becomes the call target,
which may no longer be considered part of the function. The computed address for
an indirect <emphasis>BRANCH</emphasis> or <emphasis>RETURN</emphasis> instruction becomes
the target address of an indirect <emphasis>CALL</emphasis>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">RETURN Override</emphasis></term>
<listitem>
<para>
Treats an indirect <emphasis>BRANCH</emphasis> or <emphasis>CALL</emphasis>
instruction as if it were a <emphasis>RETURN</emphasis> instruction, terminating
the control-flow path within the function. The computed destination address is
considered part of the return mechanism of the function and may no longer be
explicitly displayed in the output.
An indirect <emphasis>BRANCH</emphasis> no longer invokes switch analysis during
decompilation.
</para>
</listitem>
</varlistentry>
</variablelist>
</informalexample>
</para>
</sect2>
</section>
<section id="AnnoteComments">
<title>Comments</title>
<para>
The Decompiler automatically incorporates comments from the Program database into its
output. Comments in Ghidra are centralized and can be created and displayed by multiple
Program views, including the Decompiler. Comments created from a Decompiler window will
show up in a Listing window for instance, and vice versa.
</para>
<para>
For the purposes of understanding comments within the Decompiler, keep in mind that:
<informalexample>
<itemizedlist mark='bullet'>
<listitem>
An individual comment is associated with a specific <emphasis>address</emphasis> in the Program.
</listitem>
<listitem>
There are 5 different types of comments:
<itemizedlist mark='circle'>
<listitem>
<emphasis>Plate</emphasis>
</listitem>
<listitem>
<emphasis>Pre</emphasis>
</listitem>
<listitem>
<emphasis>Post</emphasis>
</listitem>
<listitem>
<emphasis>End-of-line (EOL)</emphasis>
</listitem>
<listitem>
<emphasis>Repeatable</emphasis>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
</informalexample>
</para>
<para>
For general documentation on creating and editing comments within Ghidra, see
<link xlink:href="help/topics/CommentsPlugin/Comments.htm">Comments</link>.
</para>
<sect2 id="CommentDisplay">
<title>Display</title>
<para>
The Decompiler collects and displays comments associated with any address in the
formal <emphasis>function body</emphasis> currently decompiling.
The comments are integrated line by line into the decompiled code, and an
individual comment is displayed on the line <emphasis>before</emphasis> the
line of code incorporating the instruction associated with the comment's
address.
</para>
<para>
Because a single line of code typically encompasses multiple machine instructions,
there is a possibility that multiple comments at different addresses apply to
the same line. In this case, the Decompiler displays each comment on its
own line, in address order, directly before the line of code.
</para>
<para>
Because the output of the Decompiler can be a heavily transformed version compared
to the original machine instructions, it is possible that individual instructions
no longer have explicit tokens representing them in the output. Comments attached
to these instruction will still be displayed in the Decompiler output with the
closest associated line of code, usually within the same basic block.
</para>
<para>
By default, the Decompiler displays only the <emphasis>Pre</emphasis> comments
within the body of the function. It also displays <emphasis>Plate</emphasis>
comments, but only if they are attached to the <emphasis>entry point</emphasis>
of the function. In this case, they are displayed first in the Decompiler output,
along with WARNING comments, before the function declaration. Other comment
types can be configured to be part of Decompiler output by changing the
Decompiler display options (see <xref linkend="CommentOptions"/>).
</para>
<warning>
Unlike a Listing window, the Decompiler does not alter how a comment is
displayed based on its type.
All enabled types of comment are displayed in the same way, on
a separate line before the line of code associated with the address.
</warning>
</sect2>
<sect2 id="CommentUnreachable">
<title>Unreachable Blocks</title>
<para>
The Decompiler may decide as part of its analysis that individual
<emphasis>basic blocks</emphasis> are unreachable and not display them in the output.
In this case, any comments associated with addresses in the unreachable block
will also not be displayed.
</para>
</sect2>
<sect2 id="CommentWarnings">
<title>Warning Comments</title>
<para>
The Decompiler can generate internal warnings during its analysis and will incorporate
them into the output as comments in the same way as the user-defined
comments described above. They are not part of Ghidra's comment system, however, and
cannot be edited. They can be distinguished from normal comments by the word
'WARNING' at the beginning of the comment.
<informalexample>
<code>/* WARNING: ... */</code>
</informalexample>
</para>
</sect2>
</section>
<section id="AnnoteVariables">
<title>Variable Annotations</title>
<para>
Variable annotations are the most important way to get names and data-types
that are meaningful to the user incorporated into the Decompiler's output.
A <emphasis role="bold">variable</emphasis> in this context is loosely defined
as any piece of memory that code in the Program treats as a logical entity.
The Decompiler works to incorporate all forms of annotation into its output
for any variable pertinent to the function being analyzed.
</para>
<para>
At a minimum, a variable annotation in Ghidra provides a:
<informalexample>
<itemizedlist mark='bullet'>
<listitem>
<emphasis role="bold">Symbol name</emphasis>,
</listitem>
<listitem>
<emphasis role="bold">Data-type</emphasis>, and
</listitem>
<listitem>
<emphasis role="bold">Storage location</emphasis>.
</listitem>
</itemizedlist>
</informalexample>
</para>
<sect2 id="VariableCreate">
<title>Creating Variable Annotations</title>
<para>
Ghidra provides various ways that a name and other attributes can be ascribed
to a variable. These break up roughly into <emphasis>global</emphasis> variables,
defined directly on memory in the Program image, and variables that are
<emphasis>local</emphasis> to a function.
</para>
<para>
Global variable annotations are created from the tool by applying a data-type to a memory
location in a Listing window, either by invoking a command from the <emphasis>Data</emphasis>
pop-up menu or by dragging a data-type from the <emphasis>Data Type Manager</emphasis>
window directly onto the memory location. Refer to the documentation:
<informalexample>
<itemizedlist mark='none'>
<listitem>
<link xlink:href="help/topics/DataPlugin/Data.htm#ApplyDataType">Applying Data Type</link>
</listitem>
</itemizedlist>
</informalexample>
</para>
<para>
Local variables annotations are created from the Listing using various editor dialogs. See, in particular:
<informalexample>
<itemizedlist mark='none'>
<listitem>
<link xlink:href="help/topics/FunctionPlugin/Variables.htm#Edit_Function">Function Signature Dialog</link>
</listitem>
<listitem>
<link xlink:href="help/topics/StackEditor/StackEditor.html">Stack Frame Editor</link>
</listitem>
<listitem>
<link xlink:href="help/topics/ReferencesPlugin/References_from.htm#Create_Default_Reference">Creating a Default Reference</link>
</listitem>
</itemizedlist>
</informalexample>
</para>
<para>
The <emphasis>Decompiler</emphasis> window also provides numerous ways of annotating variables, both local and global. In particular,
see the commands:
<informalexample>
<itemizedlist mark='none'>
<listitem>
<xref linkend="ActionRenameVariable"/>
</listitem>
<listitem>
<xref linkend="ActionRetypeVariable"/>
</listitem>
<listitem>
<xref linkend="ActionCommitParams"/>
</listitem>
<listitem>
<xref linkend="ActionCommitLocals"/>
</listitem>
</itemizedlist>
</informalexample>
</para>
</sect2>
<sect2 id="VariableSymbol">
<title>Variable Symbols</title>
<para>
Ghidra maintains its own symbol table that supports namespaces and function
scopes, and variable names are automatically incorporated into this.
In order to widely accommodate different use cases, Ghidra's symbol
table has extremely lax naming rules. Ghidra
may allow names that conflict with the stricter rules of the language
the Decompiler is attempting to produce. The Decompiler does not currently
have an option that checks for this. Users should be aware of:
<informalexample>
<variablelist>
<?dbfo list-presentation="blocks"?>
<varlistentry>
<term>Illegal Characters</term>
<listitem>
<para>
Ghidra symbols allow almost every printable character except
a space in a symbol name; punctuation and keywords can be incorporated.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Duplicate Symbols</term>
<listitem>
<para>
Ghidra allows different functions to have the same name, even within the same
namespace, in order to model languages that support <emphasis>function overloading</emphasis>.
In most languages, such functions would be expected to have distinct prototypes to allow
the symbols to be distinguished in context. Ghidra and the Decompiler, however, do not check
for this, as prototypes may not be known.
</para>
</listitem>
</varlistentry>
</variablelist>
</informalexample>
</para>
<sect3 id="SymbolScope">
<title>Variable Scope</title>
<para>
All variables belong to either a <emphasis>global</emphasis> or <emphasis>local</emphasis>
scope, which directly affects how the variable is treated in the Decompiler's data-flow
analysis.
Annotations created by applying a data-type directly to a memory location in the Listing
are automatically added to the formal <emphasis>global</emphasis> namespace.
Ghidra can create other custom namespaces that are considered global in this sense, and
renaming actions provide options that let individual global annotations be moved into
these namespaces.
Dialogs that are brought up in the context of a function, like the Function Signature Editor,
create variable annotations that are local to that function.
</para>
<para>
A global variable annotation forces the Decompiler to treat the memory location as if its value
persists beyond the end of the function. The variable must <emphasis>exist</emphasis>
at all points of the function body, generally at the same memory location.
</para>
<para>
Local variables,
in contrast, do not generally exist across the whole function, but come into scope
at the instruction that first writes to them, and then exist only up to the last
instruction that reads them. The memory location storing a local variable
at one point of the function may be reused for different variables at other points.
This can cause ambiguity in how the Decompiler should treat a given memory location used
for storing local variables, which the user may want to steer. See the discussion
in <xref linkend="AnnoteStorage"/>.
</para>
<para>
</para>
</sect3>
</sect2>
<sect2 id="AnnoteDatatype">
<title>Variable Data-types</title>
<para>
Ghidra provides extensive support for naming and describing
<emphasis role="bold">data-types</emphasis> that are tailored for the Program
being analyzed. Data-types that are explicitly part of a variable annotation
are, to the extent possible, automatically incorporated
into the Decompiler's analysis.
</para>
<sect3 id="DecompilerDataTypes">
<title>Data-types Supported by the Decompiler</title>
<para>
The Decompiler understands traditional primitive data-types in all their various sizes,
like integers, floating-point numbers, booleans, and characters. It also understands
pointers, structures, and arrays, letting it support
arbitrarily complicated composite data-types. Ghidra provides
some data-types with specialized display capabilities that don't have a natural representation
in the high-level language output by the Decompiler. The Decompiler treats these as
black-box data-types, preserving the name, but treating the underlying data either as an integer
or simply as an array of bytes.
</para>
<sect4 id="TypeUndefined">
<title>Undefined</title>
<para>
The <emphasis>undefined</emphasis> data-types are supported in their various sizes:
<emphasis role="bold">undefined1</emphasis>, <emphasis role="bold">undefined2</emphasis>,
<emphasis role="bold">undefined4</emphasis>, etc. In Ghidra, the undefined
data-types let the user specify the size of a variable, while formally declaring that
other details about the data-type are unknown.
</para>
<para>
For the Decompiler, undefined data-types, as an annotation, have the important special meaning
that the Decompiler should let its analysis determine the final data-type presented in the
output for the variable (see <xref linkend="AnnoteForcing"/> below).
</para>
</sect4>
<sect4 id="TypeVoid">
<title>Void</title>
<para>
The <emphasis role="bold">void</emphasis> data-type is supported but treated specially by
the Decompiler, as does Ghidra in general. A <emphasis role="bold">void</emphasis> can be
used to indicate the absence of a return value in function prototypes, but cannot be used
as a general annotation on variables. A void pointer, <emphasis role="bold">void *</emphasis>,
is possible; the Decompiler treats it as a pointer to an unknown data-type.
</para>
</sect4>
<sect4 id="TypeInteger">
<title>Integer</title>
<para>
Integer data-types, both signed and unsigned, are supported up to a size of 8 bytes. Larger
sizes are supported internally but are generally represented as an array of bytes in
Decompiler output. Nonstandard integer sizes of 3, 5, 6, and 7 bytes are also supported.
</para>
<para>
The standard C data-type names: <emphasis role="bold">int</emphasis>, <emphasis role="bold">short</emphasis>,
<emphasis role="bold">long</emphasis>, and <emphasis role="bold">long long</emphasis> are mapped to specific sizes
based on the processor and compiler selected when importing the Program.
</para>
</sect4>
<sect4 id="TypeBoolean">
<title>Boolean</title>
<para>
A 1-byte boolean data-type is supported. Boolean constants are rendered as either the
token <emphasis role="bold">true</emphasis> or the token <emphasis role="bold">false</emphasis>.
</para>
</sect4>
<sect4 id="TypeFloat">
<title>Floating-point</title>
<para>
Floating-point sizes of 4, 8, 10, and 16 are supported, mapping in all cases currently to the
<emphasis role="bold">float</emphasis>, <emphasis role="bold">double</emphasis>,
<emphasis role="bold">float10</emphasis>, and <emphasis role="bold">float16</emphasis>
data-types, respectively. The Decompiler currently cannot display floating-point constants
that are bigger than 8 bytes.
</para>
</sect4>
<sect4 id="TypeChar">
<title>Character</title>
<para>
ASCII- and Unicode-encoded character data-types are supported for sizes of 1, 2, and 4. The size effectively
chooses between the UTF8, UTF16, and UTF32 character encodings, respectively. The standard
C data-type names <emphasis role="bold">char</emphasis> and <emphasis role="bold">wchar_t</emphasis> are
mapped to one of these sizes based on the
processor and compiler selected when importing the Program.
</para>
</sect4>
<sect4 id="TypeString">
<title>String</title>
<para>
Terminated strings, encoded either in ASCII or Unicode, are supported. The Decompiler converts
Ghidra's dedicated string data-types like <emphasis role="bold">string</emphasis> to
an array-of-characters data-type, such as <emphasis role="bold">char[]</emphasis>,
where the character size matches the encoding.
A pointer-to-character data-type like
<informalexample>
<itemizedlist mark='none'>
<listitem>
<code>char *</code> or
</listitem>
<listitem>
<code>wchar_t *</code>
</listitem>
</itemizedlist>
</informalexample>
is also treated as a potential string reference. The Decompiler can infer terminated strings if this
kind of data-type propagates to constant values during its analysis.
</para>
<para>
Strings should be fully rendered in Decompiler output,
with non-printable characters escaped using either traditional sequences like '\r', '\n' or using Unicode
escape sequences like '\xFF'.
</para>
</sect4>
<sect4 id="TypePointer">
<title>Pointer</title>
<para>
Pointer data-types are fully supported. A pointer to any other supported data-type is
possible. The data-type being pointed to, whether it is a primitive, structure, or another pointer,
informs how the Decompiler renders a dereferenced pointer or other pointer expression.
</para>
<para>
The Decompiler automatically assumes that a pointer may reference an array of the underlying data-type.
If an integer value is added to the pointer and the value is known to be a multiple of the data-type's size,
the expression is treated as either <emphasis>pointer arithmetic</emphasis> or as an array access, and the multiplication
factor is hidden. Adding smaller integers to a structure pointer typically results in a
<emphasis>field access</emphasis> expression using the '->' or other language specific token. See the discussion
on <emphasis>Structures</emphasis> below.
</para>
<para>
The default pointer size is set based on the processor and compiler selected when the Program is
imported and generally matches the size of the <emphasis role="bold">ram</emphasis> or equivalent
address space. Different pointer sizes within the same Program are possible. The Decompiler generally
expects the pointer size to match the size of the address space being pointed to, but individual
architectures can model different size pointers into the space (such as <emphasis>near</emphasis> pointers).
</para>
<para>
For processors with more than one memory address space, pointer data-types do not by default indicate
a preferred address space and can be used to reference data in any address space.
Where there is ambiguity, the Decompiler attempts to determine the correct address space from the context
of its use within the function. It is possible to create pointer data-types with an
explicitly preferred address space, see <xref linkend="AttributeAddressPointer"/>.
</para>
</sect4>
<sect4 id="TypeArray">
<title>Array</title>
<para>
Array data-types are fully supported. The array element can be any other supported data-type
with a fixed size.
</para>
<para>
For code that accesses arrays, the Decompiler keeps track of the array index and automatically
hides the underlying multiplication needed to account for the size of an element. The access is
displayed as an expression using standard square brace notation, '[' and ']'.
For an access that covers more than one array element simultaneously, the Decompiler will either
generate a pointer expression that casts to a data-type of the correct size or may generate a
special token representing the accessed portion of the array.
<informalexample>
<programlisting>
text[iVar1] = 'a'; // Assigning a character to a variable index of the array
cVar2 = text[7]; // Reading a fixed element from an array
text._8_2_ = 0x7677; // Auto-generated token indicating multiple elements are assigned at once
</programlisting>
</informalexample>
For an auto-generated token like <code>_8_2_</code>, the first integer indicates the offset in bytes
of the access from the start of the array, and the second integer indicates the number of bytes being accessed.
</para>
<para>
If more then one element is being accessed simultaneously, the Decompiler may try to split
the access into logical pieces. See the description of the analysis option for
<link linkend="AnalysisSplitArray">Splitting Array Accesses</link>.
</para>
</sect4>
<sect4 id="TypeStructure">
<title>Structure</title>
<para>
Structure data-types are fully supported. The Decompiler does not automatically infer structures
when analyzing a function; it propagates them into the function from explicitly
annotated sources, like input parameters or global variables. Decompiler-directed creation of
structures can be triggered by the user (see <xref linkend="ActionAutoStructure"/>).
</para>
<para>
For variables that are known to be structures, or pointers to structures, the Decompiler keeps
track of offsets into the variable and will render the name of the specific field being
accessed, using language specific access operators such as '.' or '->'. If the part of the
structure being accessed does not have a normal field name, either because the structure data-type
does not list a name at that position or because more than one field is being accessed
simultaneously, the Decompiler will either cast a pointer to a data-type of the correct size or
may automatically generate a token name representing the accessed portion.
<informalexample>
<programlisting>
struct1.a = 1; // Assigning an integer to a field named "a"
fVar1 = ptr->b; // Reading field "b" through a pointer
struct1._20_4_ = 0xff00ff00; // Auto-generated name for assigning multiple fields at once
</programlisting>
</informalexample>
For an auto-generated token like <code>_20_4_</code>, the first integer indicates the offset in bytes
of the access from the start of the structure, and the second integer indicates the number of bytes being accessed.
</para>
<para>
If more than one field is being accessed simultaneously, the Decompiler may try to split
the access into logical pieces. See the description of the analysis option for
<link linkend="AnalysisSplitStruct">Splitting Structure Accesses</link>.
</para>
</sect4>
<sect4 id="TypeBitField">
<title>Bitfields</title>
<para>
Bitfields are fully supported. Bitfields are a special type of integer field, defined within a structure data-type,
that does not respect byte boundaries. A bitfield can be as small as a single bit, and multiple bitfields can be packed
into a single byte or word of the structure. The Decompiler does not infer bitfields, but propagates them into
the function from structures that explicitly define them.
</para>
<para>
The Decompiler will attempt to display reads and writes to individual bitfields
using the field's name and a standard structure access operator, like '.' or '->'. This hides the
longer sequence of byte-based operations that the underlying code is using to isolate the individual bitfield
from its neighbors.
<informalexample>
<programlisting>
iVar1 = ptr->bit1; // iVar1 = ((*ptr) >> 3) & 7
struct1.bit1 = i; // struct1._0_1 = ((i & 7) << 3) | (struct1._0_1 & 0xc7)
</programlisting>
</informalexample>
</para>
<para>
If a code sequence sets multiple bitfields simultaneously, the Decompiler will display the sequence
using multiple assignment statements, one for each bitfield affected. If bitfields are read simultaneously, the
Decompiler will display each bitfield as a separate element of the expression. If a code sequence does not seem to respect
the boundaries of individual bitfields, the Decompiler will revert to using auto-generated, byte-based,
field tokens to represent the sequence.
</para>
</sect4>
<sect4 id="TypeEnum">
<title>Enumeration</title>
<para>
Enumerations are fully supported. The Decompiler can propagate enumerations from explicitly
annotated sources throughout a function onto constants, which are then displayed with the
appropriate label from the definition of the enumeration. If the constant does not match a
single value in the enumeration definition, the Decompiler attempts to build a matching
value by <emphasis>or</emphasis>-ing together multiple labels.
The Decompiler can be made to break out constants representing packed <emphasis>flags</emphasis>,
for instance, by labeling individual bit values within an enumeration.
</para>
</sect4>
<sect4 id="TypeFunction">
<title>Function Definition</title>
<para>
A <emphasis role="bold">Function Definition</emphasis> in Ghidra is a data-type that encodes
information about the parameters and return value for a generic/unspecified function.
A formal <emphasis role="bold">function pointer</emphasis> is supported by the Decompiler as a pointer
data-type that points to a Function Definition. A Function Definition specifically encodes:
<informalexample>
<itemizedlist mark='bullet'>
<listitem>
The name and data-type of each parameter.
</listitem>
<listitem>
Whether the function takes a variable number of parameters.
</listitem>
<listitem>
The data-type associated with the return value.
</listitem>
<listitem>
The name of a generic <emphasis>calling convention</emphasis>
associated with the function.
</listitem>
</itemizedlist>
</informalexample>
</para>
<para>
The Function Definition itself does not encode any storage information. Once the Function
Definition is associated with a Program, its generic calling convention maps to one of the
specific prototype models for the processor and compiler. The prototype model is then used
to assign storage for parameters and return values, wherever the Function Definition is applied.
A Function Definition is currently limited to a prototype model
with one of the following names:
<informalexample>
<itemizedlist mark='bullet'>
<listitem>
<emphasis role="bold">__stdcall</emphasis>
</listitem>
<listitem>
<emphasis role="bold">__thiscall</emphasis>
</listitem>
<listitem>
<emphasis role="bold">__fastcall</emphasis>
</listitem>
<listitem>
<emphasis role="bold">__cdecl</emphasis>
</listitem>
<listitem>
<emphasis role="bold">__vectorcall</emphasis>
</listitem>
</itemizedlist>
</informalexample>
</para>
</sect4>
<sect4 id="TypeUnion">
<title>Unions</title>
<para>
Unions data-types are fully supported. The Decompiler does not automatically infer unions
when analyzing a function; it propagates them into the function from explicitly
annotated sources, like input parameters or global variables.
</para>
<para>
A union data-type, similarly to a structure, is made up of component data-types
called <emphasis>fields</emphasis>. But unlike a structure, a union's fields all share the same underlying
storage. When the union is applied to a variable, each field potentially describes the whole variable.
At any given point where the variable is read or written, a different field may be in effect, even if the
underlying data hasn't changed. The decompiler attempts to infer the particular field by following data-flow
to or from the point of use to determine which field best aligns with the specific operations being applied to the
variable. The name of this recovered field is then printed in Decompiler output using syntax similar to that
used for structure fields.
</para>
<para>
Depending on the number and variety of fields within the union, it may not be possible
to fully distinguish which field is being used in a specific context. In this situation,
the Decompiler chooses the first field from the list of best matches. The user has the
option of changing this choice with the <xref linkend="ActionForceField"/> action.
</para>
</sect4>
<sect4 id="TypeTypedef">
<title>Typedefs</title>
<para>
Typedef data-types are fully supported. The Decompiler does not automatically infer typedefs
when analyzing a function; it propagates them into the function from explicitly annotated sources.
</para>
<para>
A <emphasis role="bold">typedef</emphasis> is copy of another data-type but with an alternate name.
In most cases it can be used interchangeably with the data-type it copies.
In general, the Decompiler treats a typedef as a distinct data-type, and it will maintain its identify
when it is assigned to variables and is propagated through data-flow.
</para>
<para>
Ghidra supports a specific set of attributes that can be placed directly on a typedef
that then distinguish it from the data-type it copies. This allows Ghidra to support some
non-standard data-types, although the typedef and its copy are no longer interchangeable.
The decompiler supports the following typedef properties:
<itemizedlist mark='none'>
<listitem>Component Offset - See <xref linkend="AttributeOffsetPointer"/></listitem>
<listitem>Address Space - See <xref linkend="AttributeAddressPointer"/></listitem>
</itemizedlist>
</para>
</sect4>
</sect3>
<sect3 id="AnnotePointerAttributes">
<title>Pointer Attributes</title>
<para>
The Decompiler supports some specialized attributes that can be applied to pointer data-types, like offsets
and address spaces (See below). Ghidra implements these attributes on top of <emphasis>typedef</emphasis> data-types only. In
order to add attributes to pointers, a typedef of the underlying pointer data-type must be created first.
Attributes can then be placed directly on the typedef from the Data Type Manager window
(See <link xlink:href="help/topics/DataTypeManagerPlugin/data_type_manager_description.htm#Pointer_Typedef_Settings">Pointer-Typedef Settings</link>).
</para>
<sect4 id="AttributeOffsetPointer">
<title>Offset Pointers</title>
<para>
An <emphasis role="bold">offset pointer</emphasis> points at a fixed offset relative to the start of its
underlying data-type. Typically the underlying data-type is a structure and the pointer points at a
specific field in the interior of the structure. But in general, the underlying data-type can be anything,
and the offset can point anywhere relative to that data-type, including either before or after.
</para>
<para>
An offset pointer is defined with all the same properties of a normal pointer. It has an underlying
data-type and a size. On top of this an <emphasis role="bold">offset</emphasis> is specified
as an integer attribute on the pointer (typedef). This is the number of bytes that need to be
added to the start of the underlying data-type to obtain the address actually being pointed at.
</para>
<para>
Because the <emphasis>underlying</emphasis> data-type does not start directly at the address
contained in the offset pointer, one can also refer to the offset pointer's
<emphasis role="bold">direct</emphasis> data-type, i.e. the data-type that <emphasis>is</emphasis>
directly at the address contained in the pointer. If the pointer's offset is positive (and small),
the direct data-type will generally be that of a field of the <emphasis>underlying</emphasis>
data-type. If the offset is bigger than the size of the underlying data-type or is negative,
the direct data-type will be <emphasis>undefined</emphasis>.
</para>
<para>
Offset pointers occur in code where the compiler has maintained knowledge of the position of
an underlying data-type relative to a pointer, even if the pointer no longer points directly at the data-type.
Because of this, the code may still access fields of the underlying data-type through the pointer.
Annotating a variable with an offset pointer allows the Decompiler to recover these accesses.
</para>
<para>
Within the Decompiler's output, the token <code>ADJ</code> is used to indicate that the code is
accessing the underlying data-type through the offset pointer. The token uses functional syntax
to indicate the particular offset pointer. Then, once the <code>ADJ</code> token is
applied, additional pointer syntax is used, i.e. <code>-></code>, to indicate what part
of the underlying data-type is being accessed.
<informalexample>
<programlisting>
ADJ(structoffptr)->field1 = 2; // Accessing the underlying structure's field
iVar1 = *ADJ(intoffptr); // Accessing the underlying integer data-type
ADJ(arrayoffptr)[4] = iVar2; // Accessing the underlying array
</programlisting>
</informalexample>
If the offset pointer appears in Decompiler output without the <code>ADJ</code> token being
applied, it is being treated as if it were a normal pointer to its direct
data-type. This generally indicates the pointer is being used to access data outside the
underlying data-type.
</para>
</sect4>
<sect4 id="AttributeAddressPointer">
<title>Address Space Pointers</title>
<para>
An <emphasis role="bold">address space pointer</emphasis> is a normal pointer data-type with a specific
address space associated to it (See <xref linkend="ConceptAddressSpace"/>). Its created by setting
the Address Space attribute on a typedef of a pointer. The attribute value is the name of the specific
address space.
</para>
<para>
Address space pointers are useful, when a program architecture supports more than one address space
containing addressable memory, such as separate <code>code</code> and <code>data</code> address spaces.
For a program and a specific section of its code that manipulates a pointer, it may not be easy to determine
which address space is being referred to. Address space pointers provide an additional annotation mechanism
to help the decompiler identify the correct address space for a pointer in context.
</para>
<para>
The Decompiler will automatically propagate an address space pointer data-type from parameters and
other annotated variables associated with a function. Any constant that the pointer reaches via propagation
is assumed to point into the address space associated with the pointer. The correct symbol can then
be looked up, further informing the Decompiler output.
</para>
</sect4>
</sect3>
<sect3 id="AnnoteForcing">
<title>Forcing Data-types</title>
<para>
The Decompiler performs <emphasis role="bold">type propagation</emphasis> as part of its analysis
on functions. Data-type information is collected from variable annotations and other sources,
which is then propagated via data flow throughout the function to other variables and
constants where the data-type may not be immediately apparent.
</para>
<para>
With few exceptions, a variable annotation is <emphasis>forcing</emphasis> on the Decompiler in the sense
that the storage location being annotated is considered an unalterable data-type source. During
type propagation, the data-type may propagate to other variables,
but the variable representing the storage location being annotated is guaranteed to have
the given name and that data-type; it will not be overridden.
</para>
<warning>
Users should be aware that variable annotations are forcing on the Decompiler and may directly
override aspects of its analysis. Because of this, variable annotations are the most powerful way
for the user to affect Decompiler output, but setting an incomplete or incorrect data-type as
part of an annotation may produce poorer Decompiler output.
</warning>
<para>
The major exception to forcing annotations is if the data-type in the annotation is <emphasis>undefined</emphasis>.
Ghidra reserves specific names to represent formally undefined data-types, such as:
<informalexample>
<itemizedlist mark='bullet'>
<listitem><emphasis role="bold">undefined1</emphasis></listitem>
<listitem><emphasis role="bold">undefined2</emphasis></listitem>
<listitem><emphasis role="bold">undefined4</emphasis></listitem>
<listitem><emphasis role="bold">undefined8</emphasis></listitem>
</itemizedlist>
</informalexample>
These allow annotations to be made even when the user doesn't have information about a variable's data-type.
The number in the name only specifies the number of bytes in the variable.
</para>
<para>
The Decompiler views a variable annotation with an undefined data-type only as an indication of what name
should be used if a variable at that storage address exists. The data-type for the variable is filled in,
using type propagation from other sources.
</para>
<para>
For annotations that specifically label a function's formal parameters or return value,
the <link linkend="PrototypeSignatureSource">Signature Source</link> also affects how they're treated by the Decompiler.
If the Signature Source is set to anything other than <emphasis>DEFAULT</emphasis>, there is a forced
one-to-one correspondence between variable annotations and actual parameters in the Decompiler's
view of the function. This is stronger than just forcing the data-type; the existence or nonexistence of
the variable itself is forced by the annotation in this case. If the Signature Source is forcing and
there are no parameter annotations, a <emphasis>void</emphasis> prototype is forced on the function.
</para>
<para>
A forcing Signature Source is set typically if debug symbols for the function are read in during
Program import (<emphasis>IMPORTED</emphasis>) or if the user manually edits the function prototype
directly (<emphasis>USER_DEFINED</emphasis>).
</para>
<para>
If an annotation and the Signature Source force a parameter to exist, specifying an
<emphasis>undefined</emphasis> data-type in the annotation still directs the Decompiler to fill in
the variable's data-type using type propagation. The same holds true for the return value; an
<emphasis>undefined</emphasis> annotation fixes the size of the return value, but the Decompiler
fills in its own data-type.
</para>
<note>
The Decompiler may still use an <emphasis>undefined</emphasis> data-type to label a variable,
even after type propagation. If a variable is simply copied around within a function and there
are no other substantive operations or annotations on the variable, the Decompiler may decide the undefined
data-type is appropriate.
</note>
</sect3>
</sect2>
<sect2 id="AnnoteStorage">
<title>Variable Storage</title>
<para>
Every variable annotation is associated with a single <emphasis>storage location</emphasis>, where the
value of the variable is stored during execution: generally a register, stack location, or an address
in the load image of the Program. The storage location does not necessarily hold the value for that
variable at all points of execution, and it is possible for the variable value to be held in
<emphasis>different</emphasis> storage locations at different points of execution. The set of execution
points where the storage location <emphasis>does</emphasis> hold the variable value is called the annotation
<emphasis role="bold">scope</emphasis>; this is distinct from, but influenced by, the scope of the
variable itself. The different types of storage location are listed below.
</para>
<sect3 id="VariableStorageImage">
<title>Load-image Address</title>
<para>
A <emphasis role="bold">load-image address</emphasis> is a concrete address in the load image of the Program,
typically in the <emphasis role="bold">ram</emphasis> address space. This kind of
storage must be backed by a formal memory block for the Program, which typically corresponds to a specific
program section, such as the <code>.text</code> or <code>.bss</code> section. Because it is in the
load image directly, an annotation with this storage shows up directly in any Listing
window and can be directly manipulated there. In much of the Ghidra documentation, these annotations
are referred to as <emphasis role="bold">Data</emphasis>. See the
<link xlink:href="help/topics/DataPlugin/Data.htm">Data</link> section, in particular.
</para>
<para>
Although specific architectures may vary, a storage location at a load image address generally
represents a formal <emphasis>global</emphasis> variable, and the annotation is in scope
across all Program execution. For the Decompiler, the storage location is treated as a
a single <emphasis>persistent</emphasis> variable in all functions that reference it. Within a
function, all distinct references (varnodes) to the storage location are merged. The Decompiler
expects a value at the storage location to exist from <emphasis>before</emphasis> the start of
the function, and any change to the value must be explicitly represented as an assignment to
the variable in Decompiler output.
</para>
</sect3>
<sect3 id="VariableStorageStack">
<title>Stack Address</title>
<para>
A <emphasis role="bold">stack address</emphasis> is an address in the <emphasis>stack frame</emphasis>
of a particular function in the Program. Formally, a stack address is defined as an offset relative to the
incoming value of the <emphasis>stack pointer</emphasis> and exists in the
<emphasis role="bold">stack</emphasis> address space associated with the function. See the discussion
in <xref linkend="ConceptAddressSpace"/>. A <emphasis role="bold">stack annotation</emphasis> then is a variable annotation
with a stack address as its storage location. It exists only in the scope of a
single function and the variable must be <emphasis>local</emphasis> to that function.
</para>
<para>
Within a <emphasis>Listing</emphasis> window, a stack annotation is displayed as part of the function header
at the entry point address of the function, with a syntax similar to:
<informalexample>
<code>undefined4 Stack[-0x14]:4 local_14</code>
</informalexample>
The middle field (the <emphasis>Variable Location</emphasis> field) indicates that the storage location is on the
stack, and the value in brackets indicates the offset of the storage location relative to the incoming
stack pointer. The value after the colon indicates the number of bytes in the storage location.
</para>
<para>
Currently, the entire body of the function is included
in the scope of any stack annotation, and the Decompiler will allow only a single variable to exist
at the stack address. A stack annotation can be a formal parameter to the function, but otherwise the
Decompiler does not expect to see a value that exists before the start of the function.
</para>
<para>
The Decompiler will continue to perform <emphasis>copy propagation</emphasis> and other transforms on
stack locations associated with a variable annotation. In particular, within Decompiler output,
if the value is simply copied to another location,
a specific write operation to a stack address may not show up as an explicit assignment to its variable.
</para>
</sect3>
<sect3 id="VariableStorageRegister">
<title>Register</title>
<para>
A variable annotation can refer to a specific <emphasis>register</emphasis> for the processor associated
with the Program. In general, such an annotation will be for a variable local to a particular function.
Within a <emphasis>Listing</emphasis> window, this annotation is displayed as part of the function header, with
syntax like:
<informalexample>
<code>int EAX:4 iVar1</code>
</informalexample>
The <emphasis>Variable Location</emphasis> field displays the name of the particular register attached to
the annotation, and the value after the colon indicates the number of bytes in the register.
</para>
<para>
For local variable annotations with a register storage location, there is an expectation that the
register may be reused for different variables at different points of execution within the function.
There may be more than one annotation, for different variables, that share the same register
storage location.
An annotation is associated with a <emphasis>first use point</emphasis> that describes where
the register first holds a value for the particular variable (see the discussion - <xref linkend="ConceptVarnodeSSA"/>).
The entire scope of the annotation is limited to the address regions between the first use point
and any points where the value is read. The Decompiler may extend the scope as part of its
<emphasis>merging</emphasis> process, but the full extent is not stored in the annotation.
</para>
</sect3>
<sect3 id="VariableStorageTemp">
<title>Temporary Register</title>
<para>
Variable annotations can have a <emphasis>temporary register</emphasis> as a storage location.
A temporary register is not specific to a processor but is produced at various stages of
the decompilation process. See the discussion of the <emphasis role="bold">unique</emphasis>
space in <xref linkend="ConceptAddressSpace"/>. These registers do not have a meaningful name, and
the specific storage address may change on successive decompilations. So, within a
<emphasis>Listing</emphasis> window, this annotation is displayed as part of the function header
with syntax like:
<informalexample>
<code>int HASH:5f96367122:4 iVar2</code>
</informalexample>
The <emphasis>Variable Location</emphasis> field displays the internal hash used to uniquely
identify the temporary register within the data flow of the function.
</para>
<para>
A temporary register annotation must be for a local variable, and as with an ordinary register,
the annotation is associated with a <emphasis>first use point</emphasis> that describes
where the temporary register first holds a value for the variable.
</para>
</sect3>
</sect2>
</section>
<section id="AnnotePrototype">
<title>Function Prototypes</title>
<para>
Every formal Function in Ghidra is associated with a set of variable annotations and other properties that
make up the <emphasis role="bold">function prototype</emphasis>. Due to the nature of reverse engineering,
the function prototype may include only partial information and may be built up over time. Individual
elements include:
<informalexample>
<variablelist>
<?dbfo list-presentation="blocks"?>
<varlistentry>
<term><emphasis role="bold">Input Parameters</emphasis></term>
<listitem>
<para>
Each formal input to the function can have a Variable Annotation that describes its name, data-type,
and storage location. The storage location applies at the moment control flow enters the function.
If annotations exist, they are shown
in a Listing window as part of the Function header, and they usually correspond directly with symbols in the
<emphasis>function declaration</emphasis> produced by the Decompiler.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">Return Value</emphasis></term>
<listitem>
<para>
The value returned by a function can have a special Variable Annotation that describes its data-type
and storage location. The storage location applies at the moment control flow exits the function. If it exists, the annotation is shown
in a Listing window as part of the Function header with the name <code><RETURN></code>, and it usually
corresponds directly with the return value in the <emphasis>function declaration</emphasis> produced by
the Decompiler.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">Auto-Parameters</emphasis></term>
<listitem>
<para>
Specific prototypes may require auto-parameters like <emphasis role="bold">this</emphasis>
or <emphasis role="bold">__return_storage_ptr__</emphasis>. These are special input parameters
that compilers may use to implement specific high-level language concepts. See the discussion
in <xref linkend="ConceptAutoParameters"/>. Within Ghidra, auto-parameters are automatically created by the
<link xlink:href="help/topics/FunctionPlugin/Variables.htm#Edit_Function">Function Editor Dialog</link>
if the desired prototype requires them.
Within a Listing window, auto-parameters look like other parameter annotations, but the storage field shows the
string <code>(auto)</code>. Decompiler output will generally display auto-parameters as explicit variables
rather than hiding them.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">Calling Convention</emphasis></term>
<listitem>
<para>
The calling convention used by the function is specified as part of the function prototype. The convention
is specified by name, referring to the formal <xref linkend="ConceptPrototypeModel"/> that describes how storage
locations are selected for individual parameters along with other information about how the compiler treats
the function. Available models are determined by the processor and compiler, but may be extended by the user
(see <xref linkend="ExtensionOptions"/>).
</para>
<para>
In the absence of input parameter and return value annotations, the Decompiler will use the prototype model as
part of its analysis to <emphasis>discover</emphasis> the input parameters and the return value of the function.
</para>
<para>
The name <emphasis role="bold">unknown</emphasis> is reserved to indicate that nothing is known about the calling convention. If
set to <emphasis role="bold">unknown</emphasis>, depending on context, the Decompiler may assign the calling convention based on
the <emphasis>Prototype Evaluation</emphasis> option (see <xref linkend="OptionProtoEval"/>), or it
may use the default calling convention for the architecture.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">Variable Arguments</emphasis></term>
<listitem>
<para>
Functions have a boolean property called <emphasis role="bold">variable arguments</emphasis>, which can be turned on
if the function is capable of being passed a variable number of inputs. This property informs the Decompiler that
the function may take additional parameters beyond any with an explicit variable annotation.
This affects decompilation of any function which calls the <emphasis>variable arguments</emphasis> function, allowing
the Decompiler to discover unlisted parameters at a given call site.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">No Return</emphasis></term>
<listitem>
<para>
A function can be marked with the <emphasis role="bold">no return</emphasis> property, meaning that once
a call is made to the function, execution will never return to the caller. The Decompiler uses this to
compute the correct control flow in any calling functions.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">In-Line</emphasis></term>
<listitem>
<para>
If the <emphasis role="bold">in-line</emphasis> property is turned on for a particular function,
it directs the Decompiler to inline the effects of the function into the decompilation of any of its calling functions.
The function will no longer appear as a direct function call in the decompilation, but all of its data flow
will be incorporated into the calling function.
</para>
<para>
This is useful for <emphasis>bookkeeping</emphasis> functions, where it is important for the Decompiler to
<emphasis>see</emphasis> its effects on the calling function. Functions that set up the stack frame for a caller or
functions that look up or dispatch a switch destination are typical examples that should be marked <emphasis>in-line</emphasis>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">Call-fixup</emphasis></term>
<listitem>
<para>
This property is similar in spirit to marking a function as <emphasis>in-line</emphasis>.
A <emphasis role="bold">call-fixup</emphasis> directs the Decompiler to replace any call to the function with a specific
chunk of raw p-code. The decompilation of any calling function no longer shows the function call, but the chunk
of p-code incorporates the called function's effects.
</para>
<para>
Call-fixups are more flexible than just inlining a function. The call-fixup chunk can be tailored to incorporate all of,
just a part of, or something different to the behavior of the function.
</para>
<para>
Call-fixups are specified by name. The name and associated p-code chunk are typically defined in the
<emphasis>compiler specification</emphasis> for the Program. Users can extend the available set
of call-fixups (see <xref linkend="ExtensionOptions"/>).
</para>
</listitem>
</varlistentry>
</variablelist>
</informalexample>
</para>
<sect2 id="PrototypeSignatureSource">
<title>Signature Source</title>
<para>
Ghidra records a <emphasis role="bold">Signature Source</emphasis> for every function,
indicating the origin of its prototype information. This is
similar to the <emphasis>Symbol Source</emphasis> attached to Ghidra's symbol annotations
(see the documentation for
<link xlink:href="help/topics/SymbolTablePlugin/symbol_table.htm#Set_Filter">Filtering</link>
in the Symbol Table). The possible types are:
<informalexample>
<itemizedlist mark='none'>
<listitem><emphasis>DEFAULT</emphasis> - for basic or no information</listitem>
<listitem><emphasis>AI</emphasis> - for information that is produced with AI assistance</listitem>
<listitem><emphasis>ANALYSIS</emphasis> - for information derived by an Analyzer</listitem>
<listitem><emphasis>IMPORTED</emphasis> - for information imported from an external source</listitem>
<listitem><emphasis>USER_DEFINED</emphasis> - for information set by the user</listitem>
</itemizedlist>
</informalexample>
</para>
<para>
Upon import of the Program, if there are debugging symbols available, Ghidra will build
annotations of the function's parameters and set the Symbol Source type to <emphasis>IMPORTED</emphasis>.
Otherwise, it will generally be set to <emphasis>DEFAULT</emphasis>.
</para>
<para>
However, Ghidra adjusts the Signature Source for a function if there is any change to the
prototype. In particular, if the user adds, removes, or edits variable annotations
for the function's parameters or return value, Ghidra automatically converts the Signature
Source to be <emphasis>USER_DEFINED</emphasis>.
</para>
<para>
If the Signature Source is set to anything other than <emphasis>DEFAULT</emphasis>, the
function's prototype information is forcing on the Decompiler (see the discussion
in <xref linkend="AnnoteForcing"/>).
</para>
</sect2>
<sect2 id="PrototypeDiscover">
<title>Discovering Parameters</title>
<para>
The input parameter and return value annotations of the function prototype, like
any variable annotations, can be forcing on the Decompiler
(see the complete discussion in <xref linkend="AnnoteForcing"/>).
But keep in mind:
</para>
<warning>
The input parameters and return value are all forced on the Decompiler as a unit based on the
<emphasis>Signature Source</emphasis>. They are all forced if the type is set to anything
other than <emphasis>DEFAULT</emphasis>; otherwise none of them are forced.
</warning>
<para>
If the function prototype's annotations are not forcing, the Decompiler will attempt to discover the parameters
and return value using the calling convention. The prototype model underlying the calling convention
dictates which storage locations can be considered as parameters and their formal ordering.
</para>
</sect2>
<sect2 id="PrototypeCustom">
<title>Custom Storage</title>
<para>
If there are parameter or return value annotations that do not agree with the calling convention that
has been set, the function prototype is said to be using <emphasis role="bold">custom storage</emphasis>.
Using the <link xlink:href="help/topics/FunctionPlugin/Variables.htm#Edit_Function">Function Editor Dialog</link>
for instance, any storage location can be specified as a parameter, and a completely custom prototype
can be built for the function.
</para>
<para>
The Decompiler will disregard the calling convention's rules in this situation and use the custom storage
locations for parameters and the return value. Other aspects of the calling convention, like the
<emphasis>unaffected</emphasis> list, will still be used.
</para>
</sect2>
</section>
<section id="AnnoteMutability">
<title>Data Mutability</title>
<para>
<emphasis role="bold">Mutability</emphasis> is a description of how values in a specific memory region,
either a single variable or a larger block, can change during Program execution based either on
properties or established rules. Ghidra recognizes the mutability settings:
<informalexample>
<itemizedlist mark='bullet'>
<listitem>Normal</listitem>
<listitem>Constant - (read-only)</listitem>
<listitem>Volatile</listitem>
</itemizedlist>
</informalexample>
Mutability affects Decompiler analysis and can have a large impact on the output.
</para>
<para>
Most memory has <emphasis role="bold">normal</emphasis> mutability;
the value at the memory location may change over the course of executing the Program, but for a given
section of code, the value will not change unless an instruction explicitly writes to it.
</para>
<para>
Mutability can be set on an entire block of memory in the Program, typically from the
<link xlink:href="help/topics/MemoryMapPlugin/Memory_Map.htm#View_Memory_Map">Memory Map</link>.
It can also be set as part of a single Variable Annotation. From a Listing window, for instance,
use the <link xlink:href="help/topics/DataPlugin/Data.htm#Data_Settings">Settings</link> dialog.
</para>
<sect2 id="MutabilityReadOnly">
<title>Read-only</title>
<para>
The <emphasis role="bold">constant</emphasis> mutability setting indicates that values within
the memory region are read-only and don't change during Program execution. If a read-only variable is
accessed in a function being analyzed by the Decompiler, its constant value, if present in the
Program's <emphasis>load image</emphasis>, replaces the variable within data flow for the
function. The Decompiler may propagate the constant and fold it in to other operations, which
can have a substantial impact on the final output.
</para>
</sect2>
<sect2 id="MutabilityVolatile">
<title>Volatile</title>
<para>
The <emphasis role="bold">volatile</emphasis> mutability setting indicates that values within
the memory region may change unexpectedly, even if the code currently executing does not directly
write to it. Accessing a variable within a volatile region, either reading or writing, can have other
side-effects on the machine state, and it cannot in general be treated as normal variable.
If a volatile variable is accessed in a function being analyzed by the Decompiler,
each access is expressed as a copy statement on its own line, separated from other expressions,
so that the its position within the code and any sequence of accesses is clearly indicated.
Any access, either read or write, will always be displayed, even if the value is not directly
used by the function. The token representing the variable will be displayed using the
<emphasis role="bold">Special</emphasis> color, highlighting that the access is volatile
(See <xref linkend="DisplayTokenColor"/>).
<informalexample>
<programlisting>
X = <emphasis role="redtext">SREG</emphasis>; // Reading volatile SREG
<emphasis role="redtext">DAT_mem_002b</emphasis> = 0x20; // Writing volatile DAT
</programlisting>
</informalexample>
</para>
</sect2>
</section>
<section id="AnnoteConstants">
<title>Constant Annotations</title>
<para>
Ghidra provides numerous actions to control how a specific constant is formatted or displayed.
An annotation can be applied directly to a constant in a Decompiler window, which always affects
Decompiler output. Or, an annotation can be applied to the constant operand of a specific machine
instruction displayed in a Listing window. In this case, to the extent possible, the Decompiler
attempts to track the operand and apply the annotation to the matching constant in the Decompiler output.
However, the constant may be transformed from its value in the original machine instruction during the Decompiler's
analysis. The Decompiler will follow the constant through one of the following simple transformations, but
otherwise the annotation will not be applied.
<informalexample>
<itemizedlist mark='bullet'>
<listitem>Signed or zero extension</listitem>
<listitem>Bitwise negation</listitem>
<listitem>Integer negation - Two's complement</listitem>
<listitem>Add or subtract 1</listitem>
</itemizedlist>
</informalexample>
</para>
<sect2 id="ConstantEquates">
<title>Equates</title>
<para>
Ghidra can create an association between a name and a constant, called an <emphasis role="bold">equate</emphasis>.
An equate is a descriptive string that is intended to replace the numeric form of the constant, and equates
across the entire Program can be viewed from the
<link xlink:href="help/topics/EquatePlugin/Equates.htm#Equate_Table">Equates Table</link>.
</para>
<para>
An equate can be applied to a machine instruction with a constant
operand by using the <link xlink:href="help/topics/EquatePlugin/Equates.htm#Set_Equate">Set Equate</link>
menu from a Listing window. If the Decompiler successfully follows the operand to a matching constant,
the equate's name is displayed as part of the Decompiler's output as well as in any Listing window.
A transformed operand is displayed as an expression, where the transforming operation is applied to
the equate symbol representing the original constant.
</para>
<para>
Alternatively, an equate can be applied directly to a constant from a Decompiler window using its
<xref linkend="ActionSetEquate"/> menu. The constant may or may not have a corresponding instruction
operand but will be displayed in Decompiler output using the descriptive string.
</para>
</sect2>
<sect2 id="ConstantConversions">
<title>Format Conversions</title>
<para>
Ghidra can apply a <emphasis role="bold">format conversion</emphasis> to any integer constant that is displayed
in Decompiler output.
</para>
<para>
A conversion can be applied to the machine instruction containing the constant
as an operand using the <link xlink:href="help/topics/EquatePlugin/Equates.htm#Convert">Convert</link> menu option
from a Listing window. If the Decompiler successfully traces the operand to a matching constant,
the format conversion is applied in the Decompiler output as well as in the Listing window.
</para>
<para>
Alternately, a conversion can be applied directly to an integer constant in a
Decompiler window using its <xref linkend="ActionConvert"/> menu option. The constant may or may not
have a corresponding instruction operand but is displayed in Decompiler output using the conversion.
</para>
<para>
Conversions applied by the Decompiler are currently limited to:
<informalexample>
<itemizedlist mark='bullet'>
<listitem>Binary - 0b01100001</listitem>
<listitem>Decimal - 97</listitem>
<listitem>Hexadecimal - 0x61</listitem>
<listitem>Octal - 0141</listitem>
<listitem>Char - 'a'</listitem>
</itemizedlist>
</informalexample>
If necessary, a header matching the format is prepended to the representation string, either "0b", "0x" or just
"0". A conversion will not switch the signedness of the constant; the signed or unsigned data-type associated
with the constant, as determined by analysis, is preserved. If the constant is negative, with a signed data-type,
the representation string will always start with a '-' character.
</para>
</sect2>
</section>
<section id="AnnoteRegister">
<title>Register Values</title>
<para>
A <emphasis role="bold">register value</emphasis> in this context is a region of code in the Program
where a specific register holds a known constant value. Ghidra maintains an explicit list of these values for
the Program (see the documentation for <link xlink:href="help/topics/RegisterPlugin/Registers.htm">Register Values</link>),
which the Decompiler can use when analyzing a function.
A register value benefits Decompiler analysis, especially if the original compiler was aware
of the constant value, as the Decompiler can recover address references calculated as offsets relative to the register
and otherwise propagate the constant.
</para>
<para>
A <emphasis>register value</emphasis> is set by highlighting the region of code in a Listing window and then invoking the
<link xlink:href="help/topics/RegisterPlugin/Registers.htm#SetRegisterValues">Set Register Values...</link> command
from the pop-up menu. The beginning and end of a region is indicated in a Listing window with
<code>assume</code> directives, and regions can be generally viewed from the
<link xlink:href="help/topics/RegisterPlugin/Registers.htm#Register_Manager">Register Manager</link> window.
</para>
<para>
In order for a particular register value to affect decompilation, the region of code associated with the
value must contain the entry point of the function, and of course the function must read from the register.
Only the initial reads of the register are replaced with the constant value.
The Decompiler will continue to respect later instructions that write to the register, even if the
instruction is inside the register value's region.
If a register value's region starts in the middle of a function, decompilation is <emphasis>not</emphasis>
affected at all.
</para>
<sect2 id="AnnoteContextRegister">
<title>Context Registers</title>
<para>
There is a special class of registers called <emphasis role="bold">context registers</emphasis> whose
values have a different affect on analysis and decompilation than described above.
</para>
<tip>
<emphasis>Context registers</emphasis> are inputs to the disassembly decoding process and directly affect which
machine instructions are created.
</tip>
<para>
The value in a context register is examined when Ghidra decodes machine instructions from the underlying
bytes in the Program. A specific value generally corresponds to a specific <emphasis>execution mode</emphasis>
of the processor. The ARM processor <emphasis>T bit</emphasis>, for instance, which selects whether the
processor is executing ARM or THUMB instructions, is modeled as a context register in Ghidra.
The same set of bytes in the Program can be decoded to machine instructions in more than one way,
depending on context register values.
</para>
<para>
Bytes are typically decoded once using context register values
established at the time of disassembly. From Ghidra's more static view of execution, a context register holds
only a single value at any point in the code, but the same context register can hold different values for
different regions of code. Setting a new value on a region of the Program will affect any subsequent disassembly
of code within that region.
</para>
<para>
If a context register value is changed for a region that has already been disassembled, in order to see
the affect of the change, the machine instructions in the region need to be cleared, and disassembly needs
to be triggered again (see the documentation on the
<link xlink:href="help/topics/ClearPlugin/Clear.htm#Clear_Code_Bytes">Clear Plugin</link>).
</para>
<para>
Values for a context register are set in the same way as for any other register, using the
<link xlink:href="help/topics/RegisterPlugin/Registers.htm#SetRegisterValues">Set Register Values...</link> command
described above. Within the
<link xlink:href="help/topics/RegisterPlugin/Registers.htm#Register_Manager">Register Manager</link> window,
context registers are generally grouped together under the <emphasis>contextreg</emphasis> pseudo-register heading.
For details about how context registers are used in processor modeling, see
the document "SLEIGH: A Language for Rapid Processor Specification."
</para>
<para>
Because context registers affect machine instructions, they also affect the underlying p-code and
have a substantial impact on decompilation. Although details vary by processor, context register
values are typically established during the initial import and analysis of a Program and aren't changed
frequently.
</para>
</sect2>
</section>
</chapter>
<chapter id="DecompilerOptions">
<title>Decompiler Options</title>
<simplesect>
<para>
This page lists configuration options that explicitly affect the behavior of the Decompiler or
its output, independent of the code that is being decompiled. The bulk of these options are
accessible by selecting the Code Browser menu
<informalexample>
<emphasis role="bold">Edit -> Tool Options...</emphasis>
</informalexample>
and then picking the <emphasis>Decompiler</emphasis> folder. The options are associated
with the particular Code Browser or other tool being used and will apply to decompilation of any Program
being analyzed by that tool. There are three categories of options, which are listed by clicking either on the
<emphasis>Decompiler</emphasis> folder or one of its two subsections.
<informalexample>
<itemizedlist mark='none'>
<listitem>
<guiicon>
<inlinemediaobject>
<imageobject>
<imagedata condition="noscaling" fileref="images/openFolder.png" contentwidth="25px" contentdepth="17px"/>
<imagedata condition="withscaling" fileref="images/openFolder.png" contentwidth="0.22in" contentdepth="0.15in"/>
</imageobject>
</inlinemediaobject>
</guiicon><emphasis>Decompiler</emphasis> - lists <xref linkend="GeneralOptions"/> that affect the engine behavior.
</listitem>
<listitem>
 <guiicon>
<inlinemediaobject>
<imageobject>
<imagedata condition="noscaling" fileref="images/document-properties.png" contentwidth="16px" contentdepth="16px"/>
<imagedata condition="withscaling" fileref="images/document-properties.png" contentwidth="0.15in" contentdepth="0.15in"/>
</imageobject>
</inlinemediaobject>
</guiicon> <emphasis>Analysis</emphasis> - lists <xref linkend="AnalysisOptions"/> that affect the Decompiler's transformation process.
</listitem>
<listitem>
 <guiicon>
<inlinemediaobject>
<imageobject>
<imagedata condition="noscaling" fileref="images/document-properties.png" contentwidth="16px" contentdepth="16px"/>
<imagedata condition="withscaling" fileref="images/document-properties.png" contentwidth="0.15in" contentdepth="0.15in"/>
</imageobject>
</inlinemediaobject>
</guiicon> <emphasis>Display</emphasis> - lists <xref linkend="DisplayOptions"/> that affect the final presentation of Decompiler output.
</listitem>
</itemizedlist>
</informalexample>
</para>
<para>
Options that are specific to the particular Program being analyzed are accessed by
selecting the Code Browser menu
<informalexample>
<emphasis role="bold">Edit -> Options for <program>...</emphasis>.
</informalexample>
Picking the <emphasis>Decompiler</emphasis> section shows <xref linkend="ProgramOptions"/>
that only affect the Decompiler. Picking the <xref linkend="ExtensionOptions"/> section
shows a table of the available prototype models, call-fixups, and callother-fixups. These
affect more than just the Decompiler but are also documented here.
</para>
</simplesect>
<section id="GeneralOptions">
<title>General Options</title>
<para>
These options govern what resources are available to the Plug-in and the Decompiler engine but do
not affect how analysis is performed or results are displayed.
</para>
<para>
<informalexample>
<variablelist>
<?dbfo list-presentation="blocks"?>
<varlistentry id="GeneralCacheSize">
<term><emphasis role="bold">Cache Size (Functions)</emphasis></term>
<listitem>
<para>
Producing decompilation results for a single function can be computationally intensive.
This option specifies the number of functions whose decompilation results
can be cached simultaneously. When navigating to a function that
has been recently cached, as when navigating back and forth between a few functions,
a new decompilation is not triggered.
</para>
</listitem>
</varlistentry>
<varlistentry id="GeneralMaxPayload">
<term><emphasis role="bold">Decompiler Max-Payload (MBytes)</emphasis></term>
<listitem>
<para>
This option limits the number of bytes that can be produced by the Decompiler process as output
when decompiling a single function. A payload includes the actual characters to be displayed in
the window, additional token markup, symbol information, and other details of the underlying
syntax tree. The limit is specified in megabytes of data. If the limit is exceeded for a single
function, decompilation is aborted for that function, and an error message
"Decompiler results exceeded payload limit ..." is displayed.
</para>
</listitem>
</varlistentry>
<varlistentry id="GeneralTimeout">
<term><emphasis role="bold">Decompiler Timeout (seconds)</emphasis></term>
<listitem>
<para>
This option sets an upper limit on the number of seconds the Decompiler spends attempting
to analyze one function before aborting.
It is currently <emphasis role="bold">not</emphasis> enforced for a Decompiler
window. Instead it applies to the DecompilerSwitchAnalyzer, the <code>analyzeHeadless</code> command, scripts, and other
plug-ins that make use of the Decompiler service.
</para>
</listitem>
</varlistentry>
<varlistentry id="GeneralMaxInstruction">
<term><emphasis role="bold">Max Instructions per Function</emphasis></term>
<listitem>
<para>
This option sets a maximum number of machine instructions that the Decompiler will attempt
to analyze for a single function, as a safeguard against analyzing a long sequence
of zeroes or other constant data. The Decompiler will quickly throw an exception if it
traces control flow into more than the indicated number of instructions.
</para>
</listitem>
</varlistentry>
<varlistentry id="GeneralMaxJumptable">
<term><emphasis role="bold">Max Entries per Jumptable</emphasis></term>
<listitem>
<para>
This option sets the maximum number of entries (addresses) that the Decompiler can
recover from analyzing a single jumptable. This serves as a sanity check that the recovered
dimensions of a jumptable are reasonable and places an upper limit on the sheer number
of addresses the Decompiler is willing to trace from a single indirect jump.
</para>
</listitem>
</varlistentry>
</variablelist>
</informalexample>
</para>
</section>
<section id="AnalysisOptions">
<title>Analysis Options</title>
<para>
These options directly affect how the Decompiler performs its analysis, either by
toggling specific analysis passes or changing how it treats various annotations.
</para>
<para>
<informalexample>
<variablelist>
<?dbfo list-presentation="blocks"?>
<varlistentry id="AnalysisAliasBlocking">
<term><emphasis role="bold">Alias Blocking</emphasis></term>
<listitem>
<para>
When deciding if an individual stack location has become dead, the Decompiler
must consider <emphasis>aliases</emphasis>, pointers onto the stack that could
be used to modify the location within a called function. One strong heuristic the Decompiler
uses is: if the user has explicitly created a variable on the stack between the
base location referenced by the pointer and the individual stack location, then
the Decompiler can assume that the pointer is not an alias of the stack location.
The alias is <emphasis>blocked</emphasis> by the explicit variable.
However, if the user's explicit variable is labeling something that isn't
really an explicit variable, like a field within a larger structure, for instance,
the Decompiler may incorrectly consider the stack location as dead and start removing
live code.
</para>
<para>
In order to support the exploratory labeling of stack locations, the user can use this
setting to specify what data-types should be considered blocking. The four options are:
<informalexample>
<itemizedlist mark='bullet'>
<listitem><emphasis role="bold">None</emphasis> - No data-type is considered blocking</listitem>
<listitem><emphasis role="bold">Structures</emphasis> - Only structures are blocking</listitem>
<listitem><emphasis role="bold">Structures and Arrays</emphasis> - Only structures and arrays are blocking</listitem>
<listitem><emphasis role="bold">All Data-types</emphasis> - All data-types are blocking</listitem>
</itemizedlist>
</informalexample>
Selecting <emphasis>None</emphasis> is the equivalent of turning off the heuristic. Selecting anything
except <emphasis>All Data-types</emphasis> allows users to safely label small variables without
knowing immediately if the stack location is part of a larger structure or array.
</para>
</listitem>
</varlistentry>
<varlistentry id="AnalysisUnreachable">
<term><emphasis role="bold">Eliminate unreachable code</emphasis></term>
<listitem>
<para>
When toggled <emphasis>on</emphasis>, the Decompiler eliminates code that it
considers unreachable. This usually happens when, due to constant propagation and other
analysis, the Decompiler decides that a boolean value controlling a conditional branch can
only take one possible value and removes the branch corresponding to the other value. Toggling
this to <emphasis>off</emphasis> lets the user see the dead code, which is typically demarcated
by the control-flow structure:
<informalexample>
<programlisting>
if (false) { ... }
</programlisting>
</informalexample>
</para>
</listitem>
</varlistentry>
<varlistentry id="AnalysisIgnoreUnimplemented">
<term><emphasis role="bold">Ignore unimplemented instructions</emphasis></term>
<listitem>
<para>
When toggled <emphasis>on</emphasis>, the Decompiler treats instructions whose semantics
have been formally marked <emphasis role="bold">unimplemented</emphasis> as if they do
nothing (no operation). Crucially, control flow falls through to the next instruction.
In this case, the Decompiler inserts the warning "Control flow ignored unimplemented
instructions" as a comment in the function header, but the exact point at which
instruction was ignored may not be clear.
If this option is toggled <emphasis>off</emphasis>, the Decompiler inserts the built-in
function <code>halt_unimplemented()</code> at the point of the unimplemented instruction, and
control flow does not fall through.
</para>
</listitem>
</varlistentry>
<varlistentry id="AnalysisInferConstants">
<term><emphasis role="bold">Infer constant pointers</emphasis></term>
<listitem>
<para>
When toggled <emphasis>on</emphasis>, the Decompiler infers a data-type for constants
it determines are likely pointers. In the basic heuristic,
each constant is considered as an address, and if that address starts a known data or function element
in the program, the constant is assumed to be a pointer. The constants are treated like
any other source of data-type information, and the inferred data-types are freely propagated by
the Decompiler to other parts of the function.
</para>
</listitem>
</varlistentry>
<varlistentry id="AnalysisNanIgnore">
<term><emphasis role="bold">NaN operations</emphasis></term>
<listitem>
<para>
This option determines how the Decompiler treats floating-point <emphasis role="bold">NaN</emphasis>
(Not a Number) operations. Many processors automatically perform NaN checks on the operands of
floating-point instructions, and unless specifically configured, these show up in Decompiler output
as <code>NAN()</code> functional tokens. Common floating-point source code operations, like
<code><</code>, <code>></code>, and <code>==</code> can generate <code>NAN</code> tokens as a
side effect, even if the original source code was not designed to handle NaN values, and the
tokens can clutter the output.
</para>
<para>
The user can optionally configure some or all of the NaN operations to be ignored, meaning that
inputs to the NaN operation are <emphasis>assumed</emphasis> to be valid floating-point values and the
<code>NAN</code> function is removed, replacing it with the value: <emphasis role="bold">false</emphasis>.
The possible settings are:
<informalexample>
<itemizedlist mark='bullet'>
<listitem><emphasis role="bold">Ignore none</emphasis> - No NaN operations are removed</listitem>
<listitem><emphasis role="bold">Ignore with comparisons</emphasis> - NaN operations associated with comparisons are removed</listitem>
<listitem><emphasis role="bold">Ignore all</emphasis> - All NaN operations are removed</listitem>
</itemizedlist>
</informalexample>
The Decompiler considers a NaN operation to be associated with a floating-point comparison if they both
can be considered boolean clauses of the same <emphasis role="bold">if</emphasis> condition.
</para>
</listitem>
</varlistentry>
<varlistentry id="AnalysisForLoops">
<term><emphasis role="bold">Recover -for- loops</emphasis></term>
<listitem>
<para>
When toggled <emphasis>on</emphasis>, the Decompiler attempts to pinpoint
variables that control the iteration over specific loops in the function body.
When these <emphasis>loop</emphasis> variables are discovered, the loop is
rendered using a standard <emphasis role="bold">for</emphasis> loop header
that contains an initializer statement, condition, and iterating statement.
<informalexample>
<programlisting>
for (iVar2 = 10; iVar2 < len; iVar2 = iVar2 + 1) { ...
</programlisting>
</informalexample>
</para>
<para>
When toggled <emphasis>off</emphasis>, the loop is displayed using
<emphasis role="bold">while</emphasis> syntax, with any initializer and
iterating statements mixed in with the loop body or preceding basic blocks.
</para>
</listitem>
</varlistentry>
<varlistentry id="AnalysisReadOnly">
<term><emphasis role="bold">Respect read-only flags</emphasis></term>
<listitem>
<para>
When toggled <emphasis>on</emphasis>, the Decompiler treats any values in memory
marked <emphasis>read-only</emphasis> as constant. If a read-only memory location is explicitly
referenced by the function being decompiled, it is considered to be unchanging, and the initial
value present in the Program is pulled into the data flow of the function as a constant.
Due to <emphasis>Constant Propagation</emphasis> and other transformations, read-only memory
can have a large effect on Decompiler output.
</para>
<para>
Typically, as part of the import process, Ghidra marks memory blocks as read-only if they
are tagged as such by a section header or other meta-data in the original binary.
Users can actively set whether specific memory regions are considered read-only through the
<emphasis>Memory Manager</emphasis>, and individual data elements can be marked
as <emphasis>constant</emphasis> via the <emphasis role="bold">Mutability</emphasis> setting
(see <xref linkend="AnnoteMutability"/>).
</para>
</listitem>
</varlistentry>
<varlistentry id="AnalysisBitfields">
<term><emphasis role="bold">Simplify bitfield access</emphasis></term>
<listitem>
<para>
When this option is active, the Decompiler attempts to identify expressions where bitfields,
as defined in structure data-types, are either being written to or read from.
Any sequence of logical operations that access an individual bitfield are collapsed into a
normal field access, displaying the bitfield's name.
<informalexample>
<programlisting>
uVar1 = my1._3_1 << 2 & 3; // Isolating a 2-bit field 'mode' within variable 'my1'
...
uVar1 = my1.mode; // The same assignment after simplification
</programlisting>
</informalexample>
</para>
</listitem>
</varlistentry>
<varlistentry id="AnalysisExtendedPrecision">
<term><emphasis role="bold">Simplify extended integer operations</emphasis></term>
<listitem>
<para>
This toggles whether the Decompiler attempts to simplify double precision arithmetic operations,
where a single logical operation is split into two parts, calculating the high and low pieces
of the result in separate instructions. Decompiler support for this kind of transform is currently
limited, and only certain constructions are simplified.
</para>
</listitem>
</varlistentry>
<varlistentry id="AnalysisPredicate">
<term><emphasis role="bold">Simplify predication</emphasis></term>
<listitem>
<para>
When this option is active, the Decompiler simplifies code sequences containing
<emphasis>predicated</emphasis> instructions. A predicated instruction is executed
conditionally based on a boolean value, the <emphasis role="bold">predicate</emphasis>,
and a sequence of instructions can share the same predicate. The Decompiler merges the
resulting <code>if/else</code> blocks that share the same predicate so that the condition is only
printed once.
</para>
</listitem>
</varlistentry>
<varlistentry id="AnalysisSplitStruct">
<term><emphasis role="bold">Split combined structure fields</emphasis></term>
<listitem>
<para>
When this option is active, the Decompiler attempts to identify places in the code where multiple
fields of a structure data-type are being moved simultaneously with a single operation. Then it splits the
operation into multiple pieces so that the logical fields can be seen individually.
When this option isn't active, the Decompiler creates an artificial token to
represent the combined fields being written to or read from.
<informalexample>
<programlisting>
struct1._20_4_ = 0xff00ff00; // Auto-generated name for assigning multiple fields at once
...
struct1.a = 0xff00; // The same assignment, after splitting
struct1.b = 0xff00;
</programlisting>
</informalexample>
</para>
</listitem>
</varlistentry>
<varlistentry id="AnalysisSplitArray">
<term><emphasis role="bold">Split combined array elements</emphasis></term>
<listitem>
<para>
When this option is active, the Decompiler attempts to identify places in the code where multiple
elements of an array are being moved simultaneously with a single operation. Then it splits the
operation into multiple pieces so each element of the array can be seen individually.
When this option isn't active, the Decompiler creates an artificial token to
represent the combined elements being written to or read from.
<informalexample>
<programlisting>
text._20_2_ = 0x4241; // Auto-generated name for assigning multiple elements at once
...
text[20] = 'A'; // The same assignment, after splitting
test[21] = 'B';
</programlisting>
</informalexample>
</para>
</listitem>
</varlistentry>
<varlistentry id="AnalysisSplitPointers">
<term><emphasis role="bold">Split pointers to combined elements</emphasis></term>
<listitem>
<para>
This options affects when the Decompiler's splitting actions are applied. See
the discussion above about
<link linkend="AnalysisSplitStruct">Splitting Structure Accesses</link> and
<link linkend="AnalysisSplitArray">Splitting Array Accesses</link>.
If this option is on, a split is performed whenever combined elements or combined
fields are copied. In particular, either the read access, or the write access, or both,
can be through a pointer.
If this option is off, splitting is limited to copies between structures or arrays at fixed
locations, either at a global address, or on the local stack.
</para>
</listitem>
</varlistentry>
<varlistentry id="AnalysisInPlace">
<term><emphasis role="bold">Use in-place assignment operators</emphasis></term>
<listitem>
<para>
When toggled <emphasis>on</emphasis>, the Decompiler employs in-place assignment operators,
such as <code>+=</code> and <code><<=</code>, in its output syntax.
</para>
</listitem>
</varlistentry>
</variablelist>
</informalexample>
</para>
</section>
<section id="DisplayOptions">
<title>Display Options</title>
<para>
These options do not change the Decompiler's analysis but only affect how the results are presented.
</para>
<para>
<informalexample>
<variablelist>
<?dbfo list-presentation="blocks"?>
<varlistentry id="DisplayBackgroundColor">
<term><emphasis role="bold">Background Color</emphasis></term>
<listitem>
<para>
Assign the background color for the Decompiler window.
</para>
</listitem>
</varlistentry>
<varlistentry id="DisplayBraceFormatting">
<term><emphasis role="bold">Brace Format for <kind-of> blocks</emphasis></term>
<listitem>
<para>
Choose how braces are placed after function declarations, or other kinds of code blocks in Decompiler output.
Formatting can be controlled for:
<informalexample>
<itemizedlist mark='bullet'>
<listitem><emphasis role="bold">function blocks</emphasis> - the main function bodies</listitem>
<listitem><emphasis role="bold">if/else blocks</emphasis> - blocks delineated by the <code>if</code> and <code>else</code> keywords</listitem>
<listitem><emphasis role="bold">loop blocks</emphasis> - blocks delineated by the <code>for</code>, <code>do</code>, and <code>while</code> keywords</listitem>
<listitem><emphasis role="bold">switch blocks</emphasis> - blocks delineated by the <code>switch</code> keyword</listitem>
</itemizedlist>
</informalexample>
The different formatting options primarily control how the opening brace is displayed relative to the line containing
the declaration or keyword starting the block. The formatting options are:
<informalexample>
<itemizedlist mark='bullet'>
<listitem><emphasis role="bold">Same line</emphasis> - opening brace placed on same line</listitem>
<listitem><emphasis role="bold">Next line</emphasis> - opening brace placed on the next line</listitem>
<listitem><emphasis role="bold">Skip one line</emphasis> - opening brace placed on line after a blank line</listitem>
</itemizedlist>
</informalexample>
</para>
<para>
The "Same line" option is consistent with K & R code formatting style. The "Next line" option is consistent with
the Allman formatting style.
</para>
</listitem>
</varlistentry>
<varlistentry id="DisplayColorDefault">
<term><emphasis role="bold">Color Default</emphasis></term>
<listitem>
<para>
Assign the color to any characters emitted by the Decompiler that do not fall into one of token types
listed below. This includes delimiter characters like commas and parentheses as well as various <emphasis>operator</emphasis>
characters.
</para>
</listitem>
</varlistentry>
<varlistentry id="DisplayTokenColor">
<term><emphasis role="bold">Color for <token></emphasis></term>
<listitem>
<para>
Assign colors to the different types of language tokens emitted by the Decompiler.
These include:
<informalexample>
<itemizedlist mark='bullet'>
<listitem><emphasis role="bold">Comments</emphasis></listitem>
<listitem><emphasis role="bold">Constants</emphasis> - including integer, floating-point, character, and string</listitem>
<listitem><emphasis role="bold">Functions names</emphasis></listitem>
<listitem><emphasis role="bold">Globals</emphasis> - names of variables with global scope</listitem>
<listitem><emphasis role="bold">Keywords</emphasis> - reserved names in the language being emitted</listitem>
<listitem><emphasis role="bold">Parameters</emphasis> - names of function input variables</listitem>
<listitem><emphasis role="bold">Types</emphasis> - names of data-types in variable declarations and casts</listitem>
<listitem><emphasis role="bold">Variables</emphasis> - names of local variables</listitem>
<listitem><emphasis role="bold">Special</emphasis> - volatile variables and other special symbols</listitem>
</itemizedlist>
</informalexample>
</para>
</listitem>
</varlistentry>
<varlistentry id="DisplayCurrentHighlight">
<term><emphasis role="bold">Color for Current Variable Highlight</emphasis></term>
<listitem>
<para>
Assign the background color used to highlight the token currently under the cursor in a Decompiler window.
</para>
</listitem>
</varlistentry>
<varlistentry id="DisplayFindHighlight">
<term><emphasis role="bold">Color for Highlighting Find Matches</emphasis></term>
<listitem>
<para>
Assign the background color used to highlight characters matching the current <emphasis>Find</emphasis> pattern
(see <xref linkend="ActionFind"/>).
</para>
</listitem>
</varlistentry>
<varlistentry id="MiddleMouseColor">
<term><emphasis role="bold">Color for Highlighting Middle-mouse Matches</emphasis></term>
<listitem>
<para>
Assign the background color used to highlight characters when highlighting using the middle-mouse button.
</para>
</listitem>
</varlistentry>
<varlistentry id="DisplayCommentIndent">
<term><emphasis role="bold">Comment line indent level</emphasis></term>
<listitem>
<para>
Set the number of characters that comment lines are indented within Decompiler output. This applies only
to comments within the body of the function being displayed. Comments at the head of the function
are not indented.
</para>
</listitem>
</varlistentry>
<varlistentry id="DisplayCommentStyle">
<term><emphasis role="bold">Comment style</emphasis></term>
<listitem>
<para>
Set the language syntax used to delimit comments emitted as part of Decompiler output. For C and Java,
the choices are <code>/* C style comments */</code> and <code>// C++ style comments</code>.
</para>
</listitem>
</varlistentry>
<varlistentry id="DisplayDisableCasts">
<term><emphasis role="bold">Disable printing of type casts</emphasis></term>
<listitem>
<para>
Set whether the syntax for <emphasis>type casts</emphasis> is emitted in Decompiler output.
If this is toggled on, type cast syntax is never displayed, even when rules of the language
require it. So individual statements may no longer be formally accurate.
</para>
</listitem>
</varlistentry>
<varlistentry id="CommentOptions">
<term><emphasis role="bold">Display <kind-of> Comments</emphasis></term>
<listitem>
<para>
Set whether a specific type of comment should be incorporated into Decompiler output.
Each type has its own toggle and can be individually included or excluded from Decompiler output.
<informalexample>
<itemizedlist mark='bullet'>
<listitem>
<emphasis role="bold">EOL</emphasis>
</listitem>
<listitem>
<emphasis role="bold">PLATE</emphasis> - Whether plate comments <emphasis>within the body of the function</emphasis> are displayed
</listitem>
<listitem>
<emphasis role="bold">POST</emphasis>
</listitem>
<listitem>
<emphasis role="bold">PRE</emphasis>
</listitem>
</itemizedlist>
</informalexample>
A comment's type indicates how it is placed within a Listing window, not how it is placed in
a Decompiler window. All comments within the body of the function are displayed in the same way
by the decompiler, regardless of their type (see the discussion in <xref linkend="AnnoteComments"/>).
</para>
</listitem>
</varlistentry>
<varlistentry id="DisplayHeaderComment">
<term><emphasis role="bold">Display Header comment</emphasis></term>
<listitem>
<para>
Toggle whether the Decompiler emits comments at the head (before the beginning) of a function.
The header is built from Plate comments placed at the <emphasis>entry point</emphasis> of the
function (see the discussion in <xref linkend="AnnoteComments"/>).
The inclusion of other Plate comments is controlled by the <emphasis role="bold">Display PLATE comments</emphasis> toggle, described above.
</para>
</listitem>
</varlistentry>
<varlistentry id="DisplayLineNumbers">
<term><emphasis role="bold">Display Line Numbers</emphasis></term>
<listitem>
<para>
Toggle whether line numbers are displayed in any Decompiler window. If toggled
on, each Decompiler window reserves space to display a numbers down the left
side of the window, labeling each line of output produced by the Decompiler.
Line numbers are associated with the window itself and are not formally part of
the Decompiler's output.
</para>
</listitem>
</varlistentry>
<varlistentry id="DisplayNamespaces">
<term><emphasis role="bold">Display Namespaces</emphasis></term>
<listitem>
<para>
Control how the Decompiler displays namespace information associated
with function and variable symbols. The possible settings are:
<informalexample>
<itemizedlist mark='bullet'>
<listitem>
<emphasis role="bold">Minimally</emphasis> - Display the minimal path that distinguishes the symbol
</listitem>
<listitem>
<emphasis role="bold">Always</emphasis> - Always display the entire namespace path
</listitem>
<listitem>
<emphasis role="bold">Never</emphasis> - Never display the namespace path
</listitem>
</itemizedlist>
</informalexample>
</para>
<para>
The <emphasis role="bold">Minimally</emphasis> setting, which is the default, will only emit the portion
of the namespace path necessary to distinguish the symbol from other symbols with the same base name used
by the function, or if a portion of the path is completely outside the function's scope.
</para>
<para>
The <emphasis role="bold">Never</emphasis> setting never displays any of the namespace path under any
circumstances and may produce output that is ambiguous and doesn't formally parse.
</para>
</listitem>
</varlistentry>
<varlistentry id="DisplayWarningComments">
<term><emphasis role="bold">Display Warning comments</emphasis></term>
<listitem>
<para>
Toggle whether Decompiler generated <emphasis>WARNING</emphasis> comments are displayed as part
of the output. The Decompiler generates these comments, independent of those laid down by users, to
indicate unusual conditions or possible errors (see <xref linkend="CommentWarnings"/>).
</para>
</listitem>
</varlistentry>
<varlistentry id="DisplayFont">
<term><emphasis role="bold">Font</emphasis></term>
<listitem>
<para>
Set the typeface used to render characters in any Decompiler window. Indentation is generally clearer
using a monospaced (fixed-width) font, but any font available to Ghidra can be used. The size of
the font can also be controlled from this option.
</para>
</listitem>
</varlistentry>
<varlistentry id="DisplayIntegerFormat">
<term><emphasis role="bold">Integer format</emphasis></term>
<listitem>
<para>
Set how integer constants are formatted in the Decompiler output.
The possible settings are:
<informalexample>
<itemizedlist mark='bullet'>
<listitem>
<emphasis role="bold">Force Hexadecimal</emphasis> - Always use a hexadecimal representation
</listitem>
<listitem>
<emphasis role="bold">Force Decimal</emphasis> - Always use a decimal representation
</listitem>
<listitem>
<emphasis role="bold">Best Fit</emphasis> - Select the most <emphasis>natural</emphasis> representation
</listitem>
</itemizedlist>
</informalexample>
For <emphasis role="bold">Best Fit</emphasis>, a representation is selected based on how
close it is to either a <emphasis>round</emphasis> decimal value (10, 100, 1000, etc.) or
a round hexadecimal value (0x10, 0x100, 0x1000, etc.)
</para>
</listitem>
</varlistentry>
<varlistentry id="DisplayMaxChar">
<term><emphasis role="bold">Maximum characters in a code line</emphasis></term>
<listitem>
<para>
Set the maximum number of characters in a line of code emitted by the Decompiler before a line break
is forced. The Decompiler will not split an individual token across lines. So line breaks frequently
will come before the maximum number of characters is reached, and technically a single token can
extend the line beyond the maximum.
</para>
</listitem>
</varlistentry>
<varlistentry id="DisplayIndentLevel">
<term><emphasis role="bold">Number of characters per indent level</emphasis></term>
<listitem>
<para>
Set the amount of indenting used to print statements within a nested scope in the
Decompiler output. Each level of nesting (function bodies,
loop bodies, <emphasis role="bold">if/else</emphasis> bodies, etc.)
adds this number characters.
</para>
</listitem>
</varlistentry>
<varlistentry id="DisplayNull">
<term><emphasis role="bold">Print 'NULL' for null pointers</emphasis></term>
<listitem>
<para>
Set how null pointers are displayed in Decompiler output. If this is toggled
on, the Decompiler will print a constant pointer value of zero (a <emphasis role="bold">null</emphasis> pointer)
using the special token <code>NULL</code>. Otherwise the pointer value is represented with the '0' character,
which is then cast to a pointer.
</para>
</listitem>
</varlistentry>
<varlistentry id="DisplayConvention">
<term><emphasis role="bold">Print calling convention name</emphasis></term>
<listitem>
<para>
Set whether the <emphasis>calling convention</emphasis> is printed as part of the function
declaration in Decompiler output. If this option is turned on, the name of the calling convention
is printed just prior to the return value data-type within the function declaration. All functions
in Ghidra have an associated calling convention (or prototype model) that is used during
Decompiler analysis (see the discussion in <xref linkend="ConceptPrototypeModel"/>).
</para>
</listitem>
</varlistentry>
</variablelist>
</informalexample>
</para>
</section>
<section id="ProgramOptions">
<title>Program Options</title>
<para>
Changes to these options affect only the Decompiler and only for
the current Program being analyzed.
</para>
<para>
<informalexample>
<variablelist>
<?dbfo list-presentation="blocks"?>
<varlistentry id="OptionProtoEval">
<term><emphasis role="bold">Prototype Evaluation</emphasis></term>
<listitem>
<para>
Sets the calling convention (prototype model) used when decompiling a function where
the convention is not known; i.e., marked as <emphasis role="bold">unknown</emphasis>. Many architectures have multiple
calling conventions, <emphasis role="bold">__stdcall</emphasis>, <emphasis role="bold">__thiscall</emphasis>, etc.
(see the discussion in <xref linkend="ConceptPrototypeModel"/>).
</para>
</listitem>
</varlistentry>
</variablelist>
</informalexample>
</para>
</section>
<section id="ExtensionOptions">
<title>Specification Extensions</title>
<para>
This entry displays elements from the Program's <emphasis>compiler specification</emphasis> and
<emphasis>processor specification</emphasis> and allows the user to add or remove
<emphasis role="bold">extensions</emphasis>, including prototype models, call-fixups, and
callother-fixups.
</para>
<para>
Every program has a <emphasis>core</emphasis> set of specification elements,
loaded from the <xref linkend="ConceptSpecification"/>, that cannot
be modified or removed. Extensions, however, can be added to this core specification. Any extension
imported from this dialog is directly associated with the active Program and is stored permanently
with it.
</para>
<para>
Users can change or reimport an extension if new information points to a better definition.
Users have full control over an extension, and unlike a core element, can tailor it specifically
to the Program.
</para>
<para>
This options entry presents a table of all specification elements.
Each element, whether core or an extension, is displayed on a separate row with three columns:
<informalexample>
<itemizedlist mark='none' spacing='compact'>
<listitem><emphasis role="bold">Extension Type</emphasis> - indicating the type of element</listitem>
<listitem><emphasis role="bold">Name</emphasis> - showing the formal name of the element</listitem>
<listitem><emphasis role="bold">Status</emphasis> - indicating whether the element is core or an extension</listitem>
</itemizedlist>
</informalexample>
The core elements of the specification have a blank Status column, and any extension
is labeled either as <emphasis role="bold">extension</emphasis> or <emphasis role="bold">override</emphasis>.
</para>
<sect2 id="ExtendTypes">
<title>Extension Types</title>
<para>
Each of the element types described here represents an XML tag of the same name, which, if
present in the table, must either be in the <emphasis>compiler specification</emphasis> file,
the <emphasis>processor specification</emphasis> file, or provided to Ghidra as an
import document.
<informalexample>
<variablelist>
<?dbfo list-presentation="blocks"?>
<varlistentry>
<term><emphasis role="bold">prototype</emphasis></term>
<listitem>
<para>
This element is a named <xref linkend="ConceptPrototypeModel"/> that holds a specific set
of parameter-passing details. It
can be applied to individual functions by name, typically via the <emphasis role="bold">Calling Convention</emphasis> menu
in the <link xlink:href="help/topics/FunctionPlugin/Variables.htm#Edit_Function">Function Editor Dialog</link>.
See the documentation on <xref linkend="AnnotePrototype"/> for how they affect decompilation.
</para>
<para>
The XML <code><prototype></code> tag always has a <emphasis role="bold">name</emphasis> attribute
that defines the formal name of the prototype model, which must be unique across all models.
<programlisting>
<![CDATA[<prototype name="__stdcall" extrapop="unknown" stackshift="4">
<input>
<pentry minsize="1" maxsize="500" align="4">
<addr offset="4" space="stack"/>
</pentry>
</input>
<output>
...]]>
</programlisting>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">callfixup</emphasis></term>
<listitem>
<para>
This element is a Call-fixup, which can be used to substitute a specific p-code
sequence for CALL instructions during decompilation, as described in
<xref linkend="AnnotePrototype"/>.
</para>
<para>
The <code><callfixup></code> tag has a <emphasis role="bold">name</emphasis>
attribute listing the formal name, which must be unique across all call-fixups.
<programlisting>
<![CDATA[<callfixup name="EH_prolog3">
<pcode>
<body><![CDATA<
EBP = ESP + 4;
tmp = * EBP;
ESP = ESP - tmp;
ESP = ESP - 24;
]]>]]><![CDATA[</body>
</pcode>
</callfixup>]]>
</programlisting>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">callotherfixup</emphasis></term>
<listitem>
<para>
This element is a Callother-fixup, which can be used to substitute a specific p-code
sequence for CALLOTHER p-code operations. A CALLOTHER
is a black-box, or unspecified p-code operation (see <xref linkend="ConceptCallother"/>).
</para>
<para>
The <code><callotherfixup></code> tag has a
<emphasis role="bold">targetop</emphasis> attribute which lists the
name of the particular CALLOTHER operation it substitutes for.
<programlisting>
<![CDATA[<callotherfixup targetop="dynamicPush">
<pcode>
<input name="amount"/>
<body><![CDATA[
RSP = RSP + amount;
]]>]]><![CDATA[</body>
</pcode>
</callotherfixup>]]>
</programlisting>
</para>
</listitem>
</varlistentry>
</variablelist>
</informalexample>
</para>
</sect2>
<sect2 id="ExtendStatus">
<title>Status</title>
<para>
The Status column labels an element as either a core specification
or an extension; it also gives an indication of whether the element
is about to be installed or removed.
</para>
<para>
With no changes pending, the column will show one of the three main values:
<informalexample>
<variablelist>
<?dbfo list-presentation="blocks"?>
<varlistentry>
<term><emphasis><blank></emphasis></term>
<listitem>
<para>
A blank Status column indicates that the element is a core part of the
specification, originating from one of the <emphasis>specification files</emphasis>.
These elements cannot be changed or removed.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">extension</emphasis></term>
<listitem>
<para>
Indicates that the element is a program-specific extension that has been
added to the specification.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">override</emphasis></term>
<listitem>
<para>
Indicates that the element, which must be a <emphasis role="bold">callotherfixup</emphasis>,
is an extension that overrides a core element with the same target. The extension
effectively replaces the p-code injection of the core element with a user-supplied one.
If this type of extension is later removed, the core element becomes active again.
</para>
</listitem>
</varlistentry>
</variablelist>
</informalexample>
</para>
<para>
If the user has either imported additional extensions or selected an extension for removal but
has not yet clicked the <emphasis>Apply</emphasis> button in the Options dialog, the Status column
may show one of the following values, indicating a pending change:
<informalexample>
<variablelist>
<?dbfo list-presentation="blocks"?>
<varlistentry>
<term><emphasis role="bold">install</emphasis></term>
<listitem>
<para>
Indicates a new extension that will be installed.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">remove</emphasis></term>
<listitem>
<para>
Indicates an extension that is about to be removed.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">replace</emphasis></term>
<listitem>
<para>
Indicates a new extension that will replace a current
extension with the same name.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">override pending</emphasis></term>
<listitem>
<para>
Indicates a new extension that will override a core element when
it is installed.
</para>
</listitem>
</varlistentry>
</variablelist>
</informalexample>
</para>
</sect2>
<sect2 id="ExtendImport">
<title>Importing a New Extension</title>
<para>
The <emphasis>Import</emphasis> button at the bottom of the
<emphasis role="bold">Specification Extensions</emphasis> pane allows the user to import one of the
three element types, <emphasis role="bold">prototype</emphasis>,
<emphasis role="bold">callfixup</emphasis>, or <emphasis role="bold">callotherfixup</emphasis>,
into the program as a new extension.
The user must supply a properly formed XML document, as a file, that fully describes the new
extension. Clicking the <emphasis>Import</emphasis> button brings up a File Chooser dialog,
from which the user must select their prepared XML file. Once <emphasis>Ok</emphasis> is
clicked, the file is read in and validated. If there are any problems with the validation, or if
the new extension's name collides with a core element, the import does not succeed and
an error message will be displayed. Otherwise, the import is accepted, and the table is updated
to indicate the pending change.
</para>
<para>
The final change to the program, installing the new extension, will not happen until the
<emphasis>Apply</emphasis> button, at the bottom of the Options dialog, is clicked.
</para>
<para>
The XML file describing the extension <emphasis>must</emphasis> have one of the tags,
<code><prototype></code>, <code><callfixup></code>, or <code><callotherfixup></code>,
as its single root element. Users can find numerous examples within the compiler
and processor specification files that come as part of Ghidra's installation
(see <xref linkend="ConceptSpecification"/>).
</para>
<para>
In the case of <emphasis role="bold">prototype</emphasis> and <emphasis role="bold">callfixup</emphasis>
elements, extensions cannot replace existing core elements, so the new extension <emphasis>must not</emphasis>
have a name that matches an existing core element. If a new <emphasis role="bold">callotherfixup</emphasis>
extension has a targetop that matches a core element, the extension is automatically treated as an override.
</para>
<para>
Existing extensions can be replaced simply by importing a new extension with the same name or targetop.
</para>
</sect2>
<sect2 id="ExtendRemove">
<title>Removing an Extension</title>
<para>
The <emphasis>Remove</emphasis> button at the bottom of the <emphasis role="bold">Specification Extensions</emphasis> pane allows
the user to remove a previously installed extension. A row from the table is selected first, which
must have a Status of <emphasis role="bold">extension</emphasis> or <emphasis role="bold">override</emphasis>.
Core elements of the specification cannot be removed.
Clicking the <emphasis>Remove</emphasis> button brings up a confirmation dialog, and if
<emphasis>Ok</emphasis> is clicked, the selected extension is marked for removal. The Status of the row
changes to <emphasis role="bold">remove</emphasis>, reflecting this.
</para>
<para>
The final change to the program, removing the extension, will not happen until the
<emphasis>Apply</emphasis> button, at the bottom of the Options dialog, is clicked.
</para>
<para>
If a <emphasis role="bold">prototype</emphasis> or <emphasis role="bold">callfixup</emphasis> is removed,
all functions are checked to see if they have the matching calling convention or call-fixup set.
A function with matching calling convention is changed to have the <emphasis>default</emphasis> convention, which is always a core element.
A function with matching call-fixup is changed to have no call-fixup.
</para>
</sect2>
</section>
</chapter>
<chapter id="DecompilerWindow">
<title>Decompiler Window</title>
<para>
To display the Decompiler window, position the cursor on a
function in the Code Browser, then select the
<guiicon>
<inlinemediaobject>
<imageobject>
<imagedata condition="noscaling" fileref="images/decompileFunction.gif" contentwidth="16px" contentdepth="16px"/>
<imagedata condition="withscaling" fileref="images/decompileFunction.gif" contentwidth="0.15in" contentdepth="0.15in"/>
</imageobject>
</inlinemediaobject>
</guiicon> icon from the tool bar, or the
<emphasis role="bold">Decompile</emphasis> option from the
<emphasis role="bold">Window</emphasis> menu in the tool.
</para>
<para>
A Decompiler window always displays one <emphasis>function</emphasis> at a time.
The initial window that comes up in the Code Browser is called the <emphasis role="bold">Main</emphasis>
window (see <xref linkend="MainWindow"/>), and it automatically decompiles and displays the function at the
<emphasis>current address</emphasis>, following the user's navigation. Other
<emphasis role="bold">Snapshot</emphasis> windows can also
be opened that show different functions at the same time (see <xref linkend="Snapshot"/>). But any window
only shows one function at a time.
</para>
<para>
Decompilation for a window is performed "on-the-fly". It automatically
incorporates the most recent labels, data-types, comments, and other annotations applied by the user. Any change
to the Program annotations (renaming, setting data-types, etc.) automatically causes each window to redecompile
its function.
</para>
<para>
The time it takes to decompile a single function is generally proportional to the number of instructions that make
up the body of the function. Large functions may require a significant amount of time to decompile, and because
decompilation is performed on-the-fly, closing a window or navigating away from a function
runs the risk of losing results that took a long time to compute.
</para>
<section id="DecompilerDisplay">
<title>Display</title>
<para>
The window shows the decompiled output for the function associated with the window in C or some other
high-level programming language. The output is tokenized following conventions of the language. Possible
token types include:
<informalexample>
<itemizedlist mark='bullet'>
<listitem><emphasis role="bold">Data-type Name</emphasis></listitem>
<listitem><emphasis role="bold">Variable Name</emphasis></listitem>
<listitem><emphasis role="bold">Variable Sub-field Name</emphasis></listitem>
<listitem><emphasis role="bold">Function Name</emphasis></listitem>
<listitem><emphasis role="bold">Operator</emphasis></listitem>
<listitem><emphasis role="bold">Label</emphasis></listitem>
<listitem><emphasis role="bold">Comment</emphasis></listitem>
<listitem><emphasis role="bold">Syntax</emphasis></listitem>
</itemizedlist>
</informalexample>
</para>
<para>
The type of token provides context for the pop-up menus, which can trigger
highlighting, navigation, renaming, and other actions within the window.
</para>
<para>
If the window starts to decompile but ultimately fails to complete the decompilation, due
to an error or cancellation, it displays a brief description of what caused the failure
instead of the normal output. Decompilation may also successfully produce output but issue
one or more warnings during the process. These warnings are integrated into the output as
source code comments starting with label <code>WARNING:</code>. They occur either at the
beginning of the function as part of the function header or at the point in the code directly
associated with the warning (see <xref linkend="CommentWarnings"/>).
</para>
</section>
<section id="MainWindow">
<title>Main Window</title>
<para>
Initially pressing
<guiicon>
<inlinemediaobject>
<imageobject>
<imagedata condition="noscaling" fileref="images/decompileFunction.gif" contentwidth="16px" contentdepth="16px"/>
<imagedata condition="withscaling" fileref="images/decompileFunction.gif" contentwidth="0.15in" contentdepth="0.15in"/>
</imageobject>
</inlinemediaobject>
</guiicon> or selecting
<emphasis role="bold">Decompile</emphasis> from the <emphasis role="bold">Window</emphasis> menu in the tool
brings up the <emphasis>main</emphasis> window. The main window always displays the function
at the <emphasis>current address</emphasis> within the Code Browser and follows as the user navigates
within the Program. Any mouse click, menu option, or other action causing the cursor to move to a new
address in the Listing also causes the main window to display the function containing that address.
Navigation to new functions is also possible from within the window by double-clicking on function
tokens (see <xref linkend="MouseActions"/>).
</para>
<sect2 id="CrossHighlighting">
<title>Cross-Highlighting</title>
<para>
The main window maintains a map between the individual variable and operator tokens displayed in
the window and the machine instructions which correspond to them. Disassembled machine instructions
are displayed by any Listing window, and having both a Listing and Decompiler window side by side
lets the user see this correspondence between the decompiled and disassembled views of the function.
Clicking on tokens in the Decompiler window causes the Listing window to navigate
to the corresponding instruction, and clicking instructions in the Listing window
causes the Decompiler window to navigate to the corresponding line. Highlighting a region of
code in either window causes the corresponding region in the other window to be highlighted.
</para>
<para>
<emphasis>Variable Name</emphasis> and <emphasis>Variable Sub-field Name</emphasis> tokens
map to the machine instruction which wrote to the variable at that point in function.
</para>
<para>
<emphasis>Operator</emphasis> tokens map to the machine instruction which performed that operation.
</para>
<para>
<emphasis>Function Name</emphasis> tokens, if they represent a call to another function, map to the
machine instruction executing the call.
</para>
<para>
<emphasis>Comment</emphasis> tokens map to the machine address associated with the comment.
</para>
<warning>
In general, the map between machine instructions and tokens is not one-to-one because the Decompiler
transforms its underlying representation of the function.
An instruction may no longer have any operator that corresponds to it in the decompiled result.
Tokens may be transformed from the natural operation of the machine instruction they are associated
with or may represent the effect of multiple instructions.
</warning>
</sect2>
</section>
<section id="LockDisplay">
<title>Disabling Auto Refresh</title>
<para>
For very large functions, the decompile window can take a significant amount of time to re-decompile
and update the display as changes are made to the program. This makes some actions frustrating,
such as renaming or retyping variables.
</para>
<para>
As a work around, you may use the lock toggle action
<imageobject>
<imagedata condition="noscaling" fileref="images/lock.gif" contentwidth="16px" contentdepth="16px"/>
<imagedata condition="withscaling" fileref="images/lock.gif" contentwidth="0.15in" contentdepth="0.15in"/>
</imageobject> .
When selected, this action will prevent the decompiler from auto refreshing for each change.
This may make the display appear to be broken since any changes will not appear to
take effect until the display is manually refreshed.
</para>
</section>
<section id="Snapshot">
<title>Snapshot Windows</title>
<para>
Pressing the
<guiicon>
<inlinemediaobject>
<imageobject>
<imagedata condition="noscaling" fileref="images/camera-photo.png" contentwidth="16px" contentdepth="16px"/>
<imagedata condition="withscaling" fileref="images/camera-photo.png" contentwidth="0.15in" contentdepth="0.15in"/>
</imageobject>
</inlinemediaobject>
</guiicon> icon
in any Decompiler window's toolbar causes a <emphasis>Snapshot</emphasis> window
to be created, which shows decompilation of the same function.
Unlike the <emphasis>main</emphasis> window however, the <emphasis>Snapshot</emphasis> window
does not change the function it displays in response to external navigation events.
A Snapshot window can be used to hold a function fixed while the user navigates to
different functions in Listing or other windows.
</para>
<para>
Multiple Snapshot windows can be brought up to show decompilation of different functions
simultaneously. Snapshot
windows are visually distinguished from the <emphasis>main</emphasis> Decompiler window
by their colored outline.
</para>
<para>
Navigating to new functions within a Snapshot window is possible when the window is
<emphasis>active</emphasis>. The window responds to the actions
<informalexample>
<itemizedlist mark='bullet'>
<listitem>Go To... <emphasis>(pressing the 'G' key)</emphasis></listitem>
<listitem>Go to previous location <emphasis>(Back)</emphasis></listitem>
<listitem>Go to next location <emphasis>(Forward)</emphasis></listitem>
</itemizedlist>
</informalexample>
</para>
<para>
Double-clicking on specific tokens within the Snapshot window may also cause it to navigate
to a new location (see <xref linkend="MouseDouble"/>).
</para>
<anchor id="EventsOut"/>
<para>
Normally, snapshot windows are completely disconnected from the location and selection
events that synchronize the main components in the tool. To allow the snapshot window
to export its location and selection, select the
<imageobject>
<imagedata condition="noscaling" fileref="images/locationOut.gif" contentwidth="16px" contentdepth="16px"/>
<imagedata condition="withscaling" fileref="images/locationOut.gif" contentwidth="0.15in" contentdepth="0.15in"/>
</imageobject>
toolbar action.
</para>
</section>
<section id="UndefinedFunction">
<title>Undefined Functions</title>
<para>
If the current location within the Code Browser is in disassembled code, but that code
is not contained in a <link linkend="AnnoteFormalFunctionBody">Formal Function Body</link>,
then the Decompiler invents a function body, on the fly, called an
<emphasis role="bold">Undefined Function</emphasis>. The background color of the window
is changed to gray to indicate this special state.
<mediaobject>
<imageobject>
<imagedata condition="noscaling" fileref="images/Undefined.png" width="100%" contentwidth="579px" contentdepth="143px" align="center"/>
<imagedata condition="withscaling" fileref="images/Undefined.png" width="100%" contentwidth="4.523in" contentdepth="1.117in" align="center"/>
</imageobject>
</mediaobject>
</para>
<para>
The <emphasis>entry point</emphasis> address of the Undefined Function is chosen by
backtracking through the code's control flow from the current location to the start of
a basic block that has no flow coming in except possibly from <emphasis>call</emphasis> instructions.
During decompilation, a function body is computed from the selected entry point (as with any function)
based on control flow up to instructions with <emphasis>terminator</emphasis> semantics.
</para>
<para>
The current address, as indicated by the cursor in the Listing for instance, is
generally <emphasis>not</emphasis> the entry point of the invented function, but the current address will be
contained somewhere in the body.
</para>
<para>
For display purposes in the window, the invented function is given a name based on the
computed entry point address with the prefix <code>UndefinedFunction</code>. The function
is assigned the default calling convention, and parameters are discovered as part of
the Decompiler's analysis.
</para>
</section>
<section id="ToolBar">
<title>Tool Bar</title>
<para>
The following actions are available by pressing the corresponding icon in the title/tool
bar at the top of each individual Decompiler window.
The action applies to the function and Decompiler results
displayed in that particular window.
</para>
<sect2 id="ToolBarExport">
<title>Export to C</title>
<para>
<guiicon>
<inlinemediaobject>
<imageobject>
<imagedata condition="noscaling" fileref="images/page_edit.png" contentwidth="16px" contentdepth="16px"/>
<imagedata condition="withscaling" fileref="images/page_edit.png" contentwidth="0.15in" contentdepth="0.15in"/>
</imageobject>
</inlinemediaobject>
</guiicon> - button
</para>
<para>
Exports the decompiled result of the current function to a file. A file chooser
dialog is displayed to select the name of the output file. If a file extension
is not specified, a ".c" is appended to the filename. If the file already exists,
a final dialog is presented to confirm that the file should be overwritten.
</para>
<para>
This action exports a single function at a time. The user can export all functions
simultaneously from the Code Browser, by selecting the menu
<emphasis role="bold">File -> Export Program...</emphasis> and then choosing
<link xlink:href="help/topics/ExporterPlugin/exporter.htm#c_cpp">C/C++</link>
from the drop-down menu. See the full documentation for
the <link xlink:href="help/topics/ExporterPlugin/exporter.htm">Export</link> dialog.
</para>
</sect2>
<sect2 id="ToolBarSnapshot">
<title>Snapshot</title>
<para>
<guiicon>
<inlinemediaobject>
<imageobject>
<imagedata condition="noscaling" fileref="images/camera-photo.png" contentwidth="16px" contentdepth="16px"/>
<imagedata condition="withscaling" fileref="images/camera-photo.png" contentwidth="0.15in" contentdepth="0.15in"/>
</imageobject>
</inlinemediaobject>
</guiicon> - button
</para>
<para>
Creates a new <emphasis>Snapshot</emphasis> window. The <emphasis>Snapshot</emphasis> window
displays the same function as the Decompiler window on which the action was triggered,
and if that window navigates to other functions, the <emphasis>Snapshot</emphasis> does not
follow but continues to display the original function (see <xref linkend="Snapshot"/>).
</para>
</sect2>
<sect2 id="ToolBarRedecompile">
<title>Re-decompile</title>
<para>
<guiicon>
<inlinemediaobject>
<imageobject>
<imagedata condition="noscaling" fileref="images/reload3.png" contentwidth="16px" contentdepth="16px"/>
<imagedata condition="withscaling" fileref="images/reload3.png" contentwidth="0.15in" contentdepth="0.15in"/>
</imageobject>
</inlinemediaobject>
</guiicon> - button
</para>
<para>
Triggers a re-decompilation of the current function displayed in the window.
Any cached results are discarded, and a full decompile is performed.
</para>
<tip>
This action is <emphasis role="bold">not</emphasis> necessary for normal reverse
engineering tasks. Re-decompilation is <emphasis>automatically</emphasis> triggered for all
Decompiler windows by any change to the Program, so the most up-to-date decompilation is
always available to the user without this action. This action is primarily a debugging
aid for plug-in developers.
</tip>
</sect2>
<sect2 id="ToolBarEliminateUnreachableCode">
<title>Eliminate Unreachable Code</title>
<para>
<guiicon>
<inlinemediaobject>
<imageobject>
<imagedata condition="noscaling" fileref="icon.decompiler.action.provider.unreachable" contentwidth="16px" contentdepth="16px"/>
<imagedata condition="withscaling" fileref="icon.decompiler.action.provider.unreachable" contentwidth="0.15in" contentdepth="0.15in"/>
</imageobject>
</inlinemediaobject>
</guiicon> - toggle button
</para>
<para>
Quickly turn off the <xref linkend="AnalysisUnreachable"/> decompiler setting.
</para>
</sect2>
<sect2 id="ToolBarRespectReadOnly">
<title>Respect Read-only Flags</title>
<para>
<guiicon>
<inlinemediaobject>
<imageobject>
<imagedata condition="noscaling" fileref="icon.decompiler.action.provider.readonly" contentwidth="16px" contentdepth="16px"/>
<imagedata condition="withscaling" fileref="icon.decompiler.action.provider.readonly" contentwidth="0.15in" contentdepth="0.15in"/>
</imageobject>
</inlinemediaobject>
</guiicon> - toggle button
</para>
<para>
Quickly turn off the <xref linkend="AnalysisReadOnly"/> decompiler setting.
</para>
</sect2>
<sect2 id="ToolBarCopy">
<title>Copy</title>
<para>
<guiicon>
<inlinemediaobject>
<imageobject>
<imagedata condition="noscaling" fileref="images/page_white_copy.png" contentwidth="16px" contentdepth="16px"/>
<imagedata condition="withscaling" fileref="images/page_white_copy.png" contentwidth="0.15in" contentdepth="0.15in"/>
</imageobject>
</inlinemediaobject>
</guiicon> - button
</para>
<para>
Copies the currently selected text in the Decompiler window to the clipboard.
</para>
</sect2>
<sect2 id="ToolBarDebug">
<title>Debug Function Decompilation</title>
<para>
This action is located in the drop-down menu on the right side of the Decompiler
window tool/title bar.
</para>
<para>
Information suitable for debugging the decompilation process for
the current function is collected and saved to an output file in
XML format. A file chooser dialog is presented to the user to
choose the output file. The file is useful when submitting bug reports
about the Decompiler as it is generally much smaller than
the entire Program and only contains information specific to the
function. Information is generated by performing the full
decompilation of the function and collecting all the data and
annotations required during the process, including instruction
bytes, symbols, data-types, and other settings affecting
decompilation.
</para>
</sect2>
<sect2 id="DataFlowGraph">
<title>Graph Data Flow</title>
<para>
This action is located in the drop-down menu on the right side of the Decompiler
window tool/title bar.
</para>
<para>
Generate a data flow graph based upon the results in the active Decompiler window,
and render it using the current Graph Service.
</para>
</sect2>
<sect2 id="ControlFlowGraph">
<title>Graph Control Flow</title>
<para>
This action is located in the drop-down menu on the right side of the Decompiler
window tool/title bar.
</para>
<para>
Generate a control flow graph based upon the results in the active Decompiler window,
and render it using the current Graph Service.
</para>
</sect2>
</section>
<section id="MouseActions">
<title>Mouse Actions</title>
<sect2 id="MouseLeft">
<title>Left-Click</title>
<para>
Moves the Decompiler window cursor and highlights the token. Within the
<emphasis>main</emphasis> window, if a token has a machine address
associated with it, a left-click generates a
<emphasis>navigation</emphasis> event to that address, which may cause other
windows to display code near that address
(see <xref linkend="CrossHighlighting"/>).
</para>
<para>
Selecting a '(' or ')' token causes it and its matching parenthesis to be
highlighted along with the entire expression they surround.
</para>
<para>
Selecting a '{' or '}' token causes it and its matching brace to be highlighted.
</para>
</sect2>
<sect2 id="MouseRight">
<title>Right-Click</title>
<para>
Moves the Decompiler window cursor, highlights the token, and brings up the menu of
context-sensitive actions. Any highlighting and navigation is identical to a
left-click. The menu actions presented depend primarily on the token type and
are tailored to the context at that point in the code.
</para>
</sect2>
<sect2 id="MouseDouble">
<title>Double-Click</title>
<para>
Navigates based on the selected symbol or other token (see below).
If the selected token represents a formal symbol,
such as a function name or a global variable, double-clicking causes a
<emphasis>navigation</emphasis> event to the address associated with the symbol.
</para>
<para>
This action is performed by clicking twice on the desired token with the <emphasis>left</emphasis>
mouse button.
<informalexample>
<variablelist>
<?dbfo list-presentation="blocks"?>
<varlistentry>
<term><emphasis role="bold">Function Symbols</emphasis></term>
<listitem><para>
Double-clicking a called function name causes the
window itself to navigate away from its current function to the called function, triggering
a new decompilation if necessary and changing its display.
</para></listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">Global Variables</emphasis></term>
<listitem><para>
Double-clicking a global
variable name does <emphasis>not</emphasis> have any effect on the Decompiler window itself,
but Listing or <emphasis>other</emphasis> windows may navigate to the
storage address of the global variable.
</para></listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">Constants</emphasis></term>
<listitem><para>
Double-clicking a token representing a constant causes the constant to be treated
as an address, and a navigation event to that address is generated. The Decompiler
window itself navigates depending again on whether the address represents a new function or not.
</para></listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">Labels</emphasis></term>
<listitem><para>
Double-clicking the label within a <emphasis>goto</emphasis> statement causes the window to navigate
to the target of the goto, within the function. The cursor is set and the window view is adjusted if
necessary to ensure that the target is visible.
</para></listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">Braces</emphasis></term>
<listitem><para>
Double-clicking a '{' or '}' token, causes the window to navigate to the <emphasis>matching</emphasis> brace
within the window. The cursor is set and the window view is adjusted if
necessary to ensure that the matching brace is visible.
</para>
<para>
Braces may also be navigated <link linkend="GoToBrace">via the keyboard</link>.
</para></listitem>
</varlistentry>
</variablelist>
</informalexample>
</para>
</sect2>
<sect2 id="MouseControlDouble">
<title>Ctrl-Double-Click</title>
<para>
Opens a new <emphasis>Snapshot</emphasis> window, navigating it to the selected symbol.
This is a convenience for immediately decompiling and displaying a called function in a
new window, without disturbing the active window. The behavior is similar to the
Double-Click action, the selected token must represent a function name symbol or possibly
a constant address, but the navigation occurs in the new Snapshot window.
</para>
<para>
This action is performed by clicking twice on the desired token with the <emphasis>left</emphasis>
mouse button, while holding down the <emphasis>Ctrl</emphasis> key.
</para>
</sect2>
<sect2 id="MouseControlShift">
<title>Ctrl-Shift-Click</title>
<para>
Generates a navigation event to the address, within the current function, associated with
the clicked token. This allows <emphasis>Snapshot</emphasis> windows to do basic
cross-highlighting in the same way as the <emphasis>main</emphasis> Decompiler window.
A ctrl-shift-click causes Listing and other windows to navigate to and display the same
portion of code currently being displayed in the Snapshot window (see <xref linkend="CrossHighlighting"/>).
</para>
<para>
This action is performed by clicking on the desired token with the <emphasis>left</emphasis> mouse
button, while holding down both the <emphasis>Ctrl</emphasis> and <emphasis>Shift</emphasis> keys.
</para>
</sect2>
<sect2 id="MouseMiddle">
<title>Middle-Click</title>
<para>
Highlights every occurrence of a variable, constant, or operator represented by the selected
token, within the Decompiler window. There are actions available from the popup menu and from
the keyboard to navigate to each highlighted token.
</para>
</sect2>
</section>
<section id="MenuActions">
<title>Pop-up Menu and Keyboard Actions</title>
<para>
Almost all the actions described in this section can be activated from the menu that pops up
when right-clicking on a token within the Decompiler window. The pop-up menu is context sensitive and
the type of token in particular (see <xref linkend="DecompilerDisplay"/>) determines what actions are available.
The token clicked provides a local context for the action and may be used to pinpoint the exact
variable or operation affected.
</para>
<para>
Many of the actions have a key binding, which, if it exists, will be listed in the pop-up menu.
If the key binding is used to activate the action, local context is determined by the current cursor
position. Key bindings can be reassigned from the
<link xlink:href="help/topics/Tool/ToolOptions_Dialog.htm#KeyBindings_Option">Key Bindings</link>
section of the <emphasis role="bold">Tool Options Dialog.</emphasis>
</para>
<sect2 id="ActionPointerOffset">
<title>Adjust Pointer Offset</title>
<para>
Create a pointer with an <emphasis>offset</emphasis> into its underlying data-type and apply it to the
selected variable.
</para>
<para>
The action is available on variable tokens that the Decompiler has already determined are pointers, and
is designed to create an <emphasis>offset pointer</emphasis>, which is a typedef with its
<emphasis>component offset</emphasis> attribute set (See <xref linkend="AttributeOffsetPointer"/>). It
brings up a dialog that allows the user to select:
<informalexample>
<itemizedlist mark='bullet'>
<listitem>An underlying data-type for the new pointer</listitem>
<listitem>A byte offset (relative to the start of the underlying data-type)</listitem>
<listitem>A name for the new pointer data-type</listitem>
</itemizedlist>
</informalexample>
If the Decompiler determines that the selected variable points into a known structure,
this information is used to prepopulate the dialog, with the structure used as the
underlying data-type.
</para>
<para>
Clicking OK in the dialog immediately creates the new pointer data-type and attaches it to the selected variable,
triggering a new decompilation. The annotation may reveal new field accesses or other markup associated with the
underlying data-type, which will be immediately visible once decompilation completes.
</para>
<para>
If the user selects the name of an offset pointer that already exists and its other properties match the dialog,
the existing pointer will be used to complete the action, rather than creating a new data-type. If an
unrelated data-type already exists with the selected name, the action cannot be completed and the dialog
will display a warning.
</para>
<note>
If the offset pointer already exists but its offset does <emphasis>not</emphasis> match the value specified
in the dialog, the user is given the option of changing the existing data-type's offset. Confirming
this change alters the existing data-type, which may affect analysis of other unrelated parts of
the program that use it.
</note>
<para>
Once an offset pointer exists, either by invoking this action or by creating it manually
(see <link xlink:href="help/topics/DataTypeManagerPlugin/data_type_manager_description.htm#Pointer_Typedef_Settings">Pointer-Typedef Settings</link>),
it can be applied to variables like any other data-type, either through the Listing window or using the
<xref linkend="ActionRetypeVariable"/> action in the Decompiler window.
</para>
</sect2>
<sect2 id="ActionAutoStructure">
<title>Auto Create Structure</title>
<para>
Automatically create a <emphasis>structure</emphasis> data-type for a selected variable
based on its use within the current function and possibly child functions.
</para>
<para>
The <emphasis>structure</emphasis> definition is filled in by examining how the variable
is used, assuming it is a pointer to the <emphasis>structure</emphasis>, tracing
data flow to all the expressions the variable is used in. LOAD and STORE operations
trigger new <emphasis>fields</emphasis> and additive offsets are traced to calculate
the offset of the fields within the <emphasis>structure</emphasis> definition.
</para>
<para>
Once the new <emphasis>structure</emphasis> is created, the selected variable is
retyped to be a pointer to the <emphasis>structure</emphasis>. Within the window,
the function is decompiled again and references to new fields in the structure
should be immediately apparent. These can be renamed or retyped from the window
to further refine the new <emphasis>structure</emphasis> definition
(see <xref linkend="ActionRenameVariable"/>).
</para>
<informalexample>
<variablelist>
<?dbfo list-presentation="blocks"?>
<varlistentry>
<term><emphasis role="bold">Auto Fill in Structure</emphasis></term>
<listitem><para>
If the selected variable is already a pointer to a <emphasis>structure</emphasis>,
this action fills in new information about the structure on top of the existing
structure definition. Depending on how the pointer is used in the current function,
new fields may be added and the data-type of <emphasis>undefined</emphasis> fields
may be changed, but other existing parts of the structure definition are preserved.
</para></listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">Auto Fill in Class Structure</emphasis></term>
<listitem><para>
If the selected variable is the <emphasis role="bold">this</emphasis> parameter for
a class method, the menu title for this action reflects this, but the action is the same.
The class's structure definition is filled in with any new information.
</para></listitem>
</varlistentry>
</variablelist>
</informalexample>
</sect2>
<sect2 id="ActionComments">
<title>Comments</title>
<para>Set or change a comment at the address of the selected token.
</para>
<para>
These actions bring up the general Comment dialog (see <link xlink:href="help/topics/CommentsPlugin/Comments.htm">Comments</link>),
which associates the comment with a specific <emphasis>address</emphasis> in the Program. For comment
actions in the Decompiler, this address is of the machine instruction most closely linked to the selected token.
Any comments generated from a Decompiler window will be visible in Listing and other windows viewing the same
section of code.
</para>
<para>
A Decompiler window can display all comment types, but this may be affected by the Display options
(see <xref linkend="AnnoteComments"/>).
</para>
<informalexample>
<variablelist>
<?dbfo list-presentation="blocks"?>
<varlistentry>
<term><emphasis role="bold">Set Plate Comment...</emphasis></term>
<listitem><para>
Brings up the dialog for setting or editing a <emphasis>Plate</emphasis> comment.
</para></listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">Set Pre Comment...</emphasis></term>
<listitem><para>
Brings up the dialog for setting or editing a <emphasis>Pre</emphasis> comment.
</para></listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">Set...</emphasis></term>
<listitem><para>
Brings up the dialog for setting or editing a comment based on the selected token.
A <emphasis>Plate</emphasis> comment is edited if the token is part
of the function's header. A <emphasis>Pre</emphasis> comment is edited otherwise.
</para></listitem>
</varlistentry>
</variablelist>
</informalexample>
</sect2>
<sect2 id="ActionCommitLocals">
<title>Commit Local Names</title>
<para>
Commit the names of any local variables discovered during the Decompiler's analysis
to the Program database as new Variable Annotations. The recovered data-type is
not committed as part of the annotation, only the name and storage location.
</para>
<para>
Parameters are not affected by this command (see <xref linkend="ActionCommitParams"/>).
The purpose of the command is to synchronize the local variables in the
Decompiler's view of a function with the formal Variable Annotations in the disassembly view,
without otherwise affecting the decompilation. After executing this command, additional changes
to local variables can be performed directly on the corresponding annotations displayed in Listing windows,
using various methods (see <xref linkend="AnnoteVariables"/>).
Data-types are not forced for new annotations, they are created with
an <emphasis>undefined</emphasis> data-type, which allows the Decompiler to refine
its view of the variable's data-type as new information becomes available
(see <xref linkend="AnnoteForcing"/>).
</para>
</sect2>
<sect2 id="ActionCommitParams">
<title>Commit Params/Return</title>
<para>
Commit the Decompiler's analysis of the input parameters and return value of the current
function as annotations to the Program database.
</para>
<para>
In the absence of either <emphasis>imported</emphasis> or <emphasis>user-defined</emphasis>
information about a function's prototype, the Decompiler performs its own analysis of what
the prototype is, determining the storage location and data-type of all parameters and the
return value. This action commits this analysis permanently for the current function
displayed in the window, creating a matching <emphasis>Variable Annotation</emphasis> for each input
parameter and the return value. The new annotations will be displayed in a
Listing window as part of the function header, and the action effectively
<emphasis>synchronizes</emphasis> the disassembly view and Decompiler's view of the function prototype.
</para>
<para>
Committed prototype information is used both when decompiling the function itself and when
decompiling other functions that call it. The committed annotations are <emphasis>forcing</emphasis>
on the Decompiler (see <xref linkend="AnnoteForcing"/>), and it will
no longer perform prototype recovery analysis for that function. The Decompiler assumes the committed parameters,
and only the committed parameters, exist and will not modify their data-types, with the
exception of parameters that are explicitly marked as having an <emphasis>undefined</emphasis>
data-type. The user must manually modify individual variables or clear the entire prototype
if they want a change (see <xref linkend="AnnoteVariables"/>).
</para>
</sect2>
<sect2 id="ActionConvert">
<title>Convert</title>
<para>
Change the displayed encoding for the integer or character constant under the cursor.
</para>
<para>
Various encodings are possible.
<informalexample>
<table xml:id="convert.htmltable" width="50%" frame="none" rules="none">
<col width="30%"/>
<col width="70%"/>
<tbody>
<tr>
<td><emphasis role="bold">Binary:</emphasis></td>
<td>0b01100001</td>
</tr>
<tr>
<td><emphasis role="bold">Decimal:</emphasis></td>
<td>97</td>
</tr>
<tr>
<td><emphasis role="bold">Hexadecimal:</emphasis></td>
<td>0x61</td>
</tr>
<tr>
<td><emphasis role="bold">Octal:</emphasis></td>
<td>0141</td>
</tr>
<tr>
<td><emphasis role="bold">Char:</emphasis></td>
<td>'a'</td>
</tr>
</tbody>
</table>
</informalexample>
</para>
<para>
This command primarily targets a constant token in the Decompiler window, but
if there is a <emphasis>scalar</emphasis> operand in an instruction that corresponds
with the selected constant, the same conversion is also applied to the scalar in any Listing
window. This is equivalent to selecting the
<link xlink:href="help/topics/EquatePlugin/Equates.htm#Convert">Convert</link> command from a
Listing window. There may not be a scalar operand directly corresponding to the selected constant, in
which case the conversion will be applied only in the Decompiler window.
</para>
<para>
The data-type of the selected token is not changed by the action, and it retains its
meaning in the decompiler output. This slightly limits the possible conversions as signed
values cannot be forced into an unsigned representation, and vice versa.
</para>
<para>
The constant's encoding can be changed by selecting a different <emphasis role="bold">Convert</emphasis>
command, or it can be returned to its <emphasis>default</emphasis> encoding by selecting
the <xref linkend="ActionRemoveEquate"/> command.
</para>
</sect2>
<sect2 id="ActionCopy">
<title>Copy</title>
<para>
Copy selected code from the Decompiler window into the clipboard.
</para>
<para>
This is part of the standard copy
capabilities for all Ghidra windows and is suitable for copying (sections of) Decompiler output
into other documents.
</para>
</sect2>
<sect2 id="ActionEditDataType">
<title>Edit Data Type</title>
<para>
Bring up a dialog for editing the definition of the data-type under the cursor.
</para>
<para>
The cursor must be on the data-type <emphasis>name</emphasis> token,
not on a variable or other syntax. The action is only available for
<emphasis>structures</emphasis> and <emphasis>unions</emphasis>,
which will bring up the <link xlink:href="help/topics/DataTypeEditors/StructureEditor.htm">Structure Editor</link>,
and for <emphasis>enumerations</emphasis>, which will bring up the
<link xlink:href="help/topics/DataTypeEditors/EnumEditor.htm">Enum Editor</link>.
</para>
<para>
Any change to the definition of the data-type is automatically incorporated by the Decompiler into its output
(see <xref linkend="AnnoteDatatype"/>).
</para>
</sect2>
<sect2 id="ActionEditSignature">
<title>Edit Function Signature</title>
<para>
Bring up a dialog for editing the <emphasis>prototype</emphasis> of a selected function and other
details about how it passes parameters.
</para>
<para>
The action is available from any token in the Decompiler window. Most tokens trigger editing
of the current function itself, but a called function can be edited by putting the cursor on
its name specifically.
</para>
<para>
<mediaobject>
<imageobject>
<imagedata condition="noscaling" fileref="images/EditFunctionSignature.png" width="100%" contentwidth="688px" contentdepth="534px" align="center"/>
<imagedata condition="withscaling" fileref="images/EditFunctionSignature.png" width="100%" contentwidth="5.375in" contentdepth="4.172in" align="center"/>
</imageobject>
</mediaobject>
The dialog provides detailed control over elements like
<informalexample>
<itemizedlist mark='none'>
<listitem>
<emphasis role="bold">Parameters</emphasis> - including name, data-type, and storage
</listitem>
<listitem>
<emphasis role="bold">Return Type</emphasis> - including data-type and storage
</listitem>
<listitem>
<emphasis role="bold">Variable Arguments</emphasis> and
</listitem>
<listitem>
<emphasis role="bold">Inlining</emphasis>
</listitem>
</itemizedlist>
</informalexample>
</para>
<para>
See documentation for the
<link xlink:href="help/topics/FunctionPlugin/Variables.htm#Edit_Function">Function Editor Dialog</link>.
The Decompiler automatically incorporates any changes into its output.
</para>
</sect2>
<sect2 id="ActionFind">
<title>Find...</title>
<para>
Search for strings within the active window, in the current Decompiler output.
</para>
<para>
The command brings up a dialog where a search pattern can be entered as a raw string or regular expression.
The search is performed directly on the text of the decompiled function, from the current cursor; forward
each time the <emphasis role="bold">Next</emphasis> button is hit, or backward for the
<emphasis role="bold">Previous</emphasis> button. Any match is highlighted in the window,
and the cursor is set to the start of the match.
</para>
</sect2>
<sect2 id="ActionForceField">
<title>Force Field</title>
<para>
Force the Decompiler to assume a specific read or write to a variable, with a <emphasis>union</emphasis> data-type,
is referring to a user selected field.
</para>
<para>
A union data-type overlays multiple other data-type interpretations
(<emphasis role="bold">fields</emphasis>) on top of one variable; any one of which may be active at
a point where the variable is accessed. The Decompiler automatically selects which field it thinks is being
referenced (See <xref linkend="TypeUnion"/>). But this action allows the user to force
the Decompiler to use a particular field.
</para>
<para>
The cursor must be on the token currently representing the union field to be changed.
The action brings up a dialog with a drop-down menu of the possible fields that can be forced.
A field must be compatible with the selected access or it will not be listed in the menu. This usually
means that the data-type of the field must be the same size as the read or write being performed.
The menu option <code>(no field)</code> may also be available, which if selected, indicates that
the Decompiler should treat the read or write as accessing the union as a whole.
Its also possible that no other field is possible but the current one. In which case, the dialog will
display a warning message and contain no drop-down menu.
</para>
<para>
Selecting a menu option and clicking OK completes the action. Subsequent decompilation should show
the new field at the selected access point, and the data-type associated with the selected field will
likely propagate further across the function, possibly triggering substantial changes to the output.
</para>
<para>
If there is more than one access to the same variable with a union data-type,
each representative field token can be forced to a new field individually.
</para>
</sect2>
<sect2 id="GoToBrace">
<title>Go To Next/Previous Brace</title>
<para>
These actions are available from the keyboard, with no equivalent pop-up menu entry.
<emphasis role="bold">Shift-Open Bracket</emphasis> will go to the previous enclosing
open brace. <emphasis role="bold">Shift-Close Bracket</emphasis> will go to the
next enclosing closing brace. These key bindings can be changed via the
<link xlink:href="help/topics/Tool/ToolOptions_Dialog.htm#KeyBindings_Option">Tool Options Dialog</link>.
</para>
<para>
Paired braces can also be navigated by double-clicking.
</para>
</sect2>
<sect2 id="GoToMiddleMouseHighlight">
<title>Go To Next/Previous Highlight</title>
<para>
These actions are available from the popup menu and keyboard. Only tokens highlighted from the
middle-mouse will be navigated. <emphasis role="bold">Shift-Comma</emphasis> will go to the
previous highlighted token. <emphasis role="bold">Shift-Period</emphasis> will go to the
next highlighted token. These key bindings can be changed via the
<link xlink:href="help/topics/Tool/ToolOptions_Dialog.htm#KeyBindings_Option">Tool Options Dialog</link>.
</para>
</sect2>
<sect2 id="ActionHighlight">
<title>Highlight</title>
<para>
All these actions highlight a specific set of variable tokens tracing the <emphasis role="bold">data flow</emphasis>
of the selected variable within the current function, defined as the directed flow
of data from input variables through operations that manipulate their value to their
output variables. The operations and variables chain together to form data-flow
<emphasis>paths</emphasis>.
</para>
<informalexample>
<variablelist>
<?dbfo list-presentation="blocks"?>
<varlistentry>
<term><emphasis role="bold">Def-Use</emphasis></term>
<listitem><para>
Highlight the single token where the selected variable was last written (def),
and highlight all the tokens where that single value is read (use). The written token,
generally where the variable is on the left-hand side of an assignment expression,
is highlighted in a different color. If the variable is written on multiple merging
control-flow paths, no written token is highlighted.
</para>
<para>
In the following example, the token representing the first write to the
variable <emphasis>a</emphasis> is selected when Def-Use is chosen.
<mediaobject>
<imageobject>
<imagedata condition="noscaling" fileref="images/Defuse.png" width="100%" contentwidth="400px" contentdepth="297px" align="center"/>
<imagedata condition="withscaling" fileref="images/Defuse.png" width="100%" contentwidth="3.125in" contentdepth="2.320in" align="center"/>
</imageobject>
</mediaobject>
</para></listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">Forward Slice</emphasis></term>
<listitem><para>
Highlight all variable tokens where the value at that point in the function is
directly affected by the value at the selected variable token.
A token is highlighted if there is a direct data-flow path
starting from the selected point and ending at the token. A call operation is not
considered a direct data-flow path from its input parameters to its output value.
</para>
<para>
In the following example, the token <emphasis>b</emphasis>, the output of
<emphasis>max_alpha</emphasis>, is selected when Forward Slice is chosen.
<mediaobject>
<imageobject>
<imagedata condition="noscaling" fileref="images/ForwardSlice.png" width="100%" contentwidth="500px" contentdepth="280px" align="center"/>
<imagedata condition="withscaling" fileref="images/ForwardSlice.png" width="100%" contentwidth="3.906in" contentdepth="2.187in" align="center"/>
</imageobject>
</mediaobject>
</para></listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">Backward Slice</emphasis></term>
<listitem><para>
Highlight all variable tokens where the value at that point in the function
directly affects the value at the selected variable token.
A token is highlighted if there is a direct data-flow path
starting from the token and ending at the selected point.
A call operation is not considered a direct data-flow path from its input parameters
to its output value.
</para></listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">Forward Operator Slice</emphasis></term>
<listitem><para>
Highlight every operator token that manipulates a value directly affected by the
value at the selected variable token. Along each direct data-flow path that
<emphasis>starts</emphasis>
at the selected point, each token representing an operation is highlighted, along with
any explicit variable read or written by the operation. A call operation is not
considered a direct data-flow path from its input parameters to its output value.
This is an alternate presentation of the slice displayed by the Forward Slice action.
</para></listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">Backward Operator Slice</emphasis></term>
<listitem><para>
Highlight every operator token that manipulates a value that directly affects the
value at the selected variable token. Along each direct data-flow path that
<emphasis>ends</emphasis>
at the selected point, each token representing an operation is highlighted, along with
any explicit variable read or written by the operation. A call operation is not
considered a direct data-flow path from its input parameters to its output value.
This is an alternate presentation of the slice displayed by the Backward Slice action.
</para></listitem>
</varlistentry>
</variablelist>
</informalexample>
</sect2>
<sect2 id="ActionSecondaryHighlight">
<title>Secondary Highlight</title>
<para>
A <emphasis>secondary highlight</emphasis> is a semi-permanent token highlight in the Decompiler
window that, unlike normal highlights, will not go away as the user clicks other tokens.
The color and text being highlighted is controlled by the user and will persist for
<emphasis role="bold">for the duration of the Ghidra session</emphasis> or until the user
explicitly removes the highlight.
</para>
<informalexample>
<variablelist>
<?dbfo list-presentation="blocks"?>
<varlistentry>
<term><emphasis role="bold">Set Highlight</emphasis></term>
<listitem><para>
Apply a secondary highlight to all text matching the text of the token under
the cursor. A color is chosen randomly for the Ghidra session. If the same highlight
is removed and then reactivated later in the session, the same color will be used.
</para></listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">Set Highlight...</emphasis></term>
<listitem><para>
Apply a secondary highlight to all text matching the text of the token under
the cursor, as in the <emphasis>Set Highlight</emphasis> action above.
A Color Chooser dialog is shown allowing the user to select the specific color
for the highlight. The dialog is initialized with a random color or with the color
previously applied to the same token.
</para></listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">Remove Highlight</emphasis></term>
<listitem><para>
Remove the existing secondary highlight applied to the token under the cursor.
Other highlights are not affected.
</para></listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">Remove All Highlights</emphasis></term>
<listitem><para>
Remove all secondary highlights in the current function. Highlights in other
functions are not affected.
</para></listitem>
</varlistentry>
</variablelist>
</informalexample>
</sect2>
<sect2 id="ActionOverrideSignature">
<title>Override Signature</title>
<para>
Override the function prototype corresponding to the function under the cursor.
</para>
<para>
This action can be triggered at a <emphasis>call site</emphasis>, where the function
being decompiled is calling into another function. Users must select either the token representing
the called function's name or one of the tokens representing the function pointer at the call site.
The action brings up a dialog where the <emphasis>function prototype</emphasis>
corresponding to the call site can be edited. The dialog provides fine-grained control of
the return data-type along with the name and data-type of each input parameter.
The function prototype properties <emphasis role="bold">Calling Convention</emphasis>,
<emphasis role="bold">In Line</emphasis>, and <emphasis role="bold">No Return</emphasis>
can also be set (see <xref linkend="AnnotePrototype"/>).
</para>
<para>
Confirming the dialog forces the new function prototype on the Decompiler's view of the called function,
but only for the single selected call site.
</para>
<para>
This action is suitable for either indirect calls or direct calls to functions taking a variable number
of arguments; situations where a complete description of all parameters is not available.
For direct calls with a fixed number of arguments, it is almost always better to provide
parameter information by setting the function's prototype directly (see the
<xref linkend="ActionCommitParams"/> command). In this situation, the "Override Signature"
command is still possible, but it will bring up a confirmation dialog.
</para>
</sect2>
<sect2 id="ActionEditOverride">
<title>Edit Signature Override</title>
<para>
Edit the overriding function prototype applied previously to the called function under the cursor.
</para>
<para>
This action can only be triggered at call sites with an existing signature override. As with the Override
Signature command, users must select either the token representing the called function's name or the
tokens representing the function pointer at the call site. The action brings up a dialog where the user
can edit the current overriding function prototype.
</para>
</sect2>
<sect2 id="ActionReference">
<title>References</title>
<sect3 id="ActionFindUses">
<title>Find Uses of <data-type></title>
<para>
Calculate locations in the Program that reference the <emphasis role="bold">data-type</emphasis>
of the token under the cursor. Results are collected in a
<link xlink:href="help/topics/LocationReferencesPlugin/Location_References.html">Location References Dialog</link>,
which displays a row for each reference with its address and other context.
</para>
<para>
Uses (references) specifically are to <emphasis>variables</emphasis> that have been assigned the data-type.
References to parameters and global variables are always listed.
If the <emphasis>Dynamic Data Type Discovery</emphasis> option is on
(see <link xlink:href="help/topics/LocationReferencesPlugin/Location_References.html#Data_Types">To Find Location References to Data Types</link>),
the Decompiler's propagation analysis is invoked on all functions to discover local
variables as well.
</para>
</sect3>
<sect3 id="ActionFindReferences">
<title>Find References to <function/global variable></title>
<para>
Display locations in the Program that reference the <emphasis role="bold">function</emphasis> or
<emphasis role="bold">global variable</emphasis> associated with the token under the cursor.
Results are collected in a
<link xlink:href="help/topics/LocationReferencesPlugin/Location_References.html">Location References Dialog</link>,
which displays a row for each reference with its address and other context.
</para>
<para>
In the case of a function, references include both instructions and data referring to the <emphasis>entry point</emphasis>
address of the function.
</para>
</sect3>
<sect3 id="ActionShowReferences">
<title>Show References to <address></title>
<para>
Display locations in the Program that reference the <emphasis role="bold">address</emphasis>
associated with the token under the cursor. Results are collected in a
<link xlink:href="help/topics/LocationReferencesPlugin/Location_References.html">Location References Dialog</link>,
which displays a row for each reference with its address and other context.
</para>
<para>
The selected address is of the instruction most closely associated with the
variable or operator represented by the token.
</para>
</sect3>
</sect2>
<sect2 id="ActionRemoveEquate">
<title>Remove Convert/Equate</title>
<para>
Remove the display <emphasis>conversion</emphasis> or <emphasis>equate</emphasis> from
the constant under the cursor.
</para>
<para>
The selected constant must have had either a <xref linkend="ActionConvert"/> or a
<xref linkend="ActionSetEquate"/> command applied to it. After applying this command,
the conversion is no longer applied, and the selected constant will be displayed
using the decompiler's default strategy, which depends on the data-type of the constant and
other display settings (See <xref linkend="DisplayIntegerFormat"/>).
</para>
</sect2>
<sect2 id="ActionRemoveOverride">
<title>Remove Signature Override</title>
<para>
Remove the overriding function prototype applied previously to the called function under the cursor.
</para>
<para>
This action can only be triggered at <emphasis>call sites</emphasis>, where an overriding
prototype was previously placed by the <xref linkend="ActionOverrideSignature"/> command. As with
this command, users must select either the token representing the called function's name or the
tokens representing the function pointer at the call site. The action causes the
override to be removed immediately. Parameter information will be drawn from the Decompiler's
normal analysis.
</para>
</sect2>
<sect2 id="ActionRemoveLabel">
<title>Remove Label</title>
<para>
Remove the label corresponding to the token under the cursor.
</para>
<para>
A label can be removed by triggering this action while the corresponding label token is
under the cursor. For more on removing labels, see
<link xlink:href="help/topics/LabelMgrPlugin/Labels.htm#Remove_Label">Removing a Label</link>.
</para>
<para>
The change will be immediately visible across all references to the label
(including in any Decompiler, Listing, and Functions windows).
</para>
</sect2>
<sect2 id="ActionRenameFunction">
<title>Rename Function</title>
<para>
Rename the function corresponding to the token under the cursor.
</para>
<para>
The current function can be renamed by selecting the name token within the function's
declaration at the top of the Decompiler window, or individual called functions
can be renamed by selecting their name token within a call expression.
This action brings up a dialog containing a text field prepopulated with the
name to be changed. The current namespace (and any parent namespaces) is
presented in a drop-down menu. Editing the text field changes the <emphasis>base</emphasis>
name of the function, and selecting within the drop-down menu allows
the function to be moved into a parent namespace.
</para>
<para>
A new or child namespace can
be specified by prepending the base name with the namespace using the C++ "::"
delimiter characters. Any namespace path entered this way is considered relative
to the namespace set in the drop-down menu, so the <emphasis role="bold">Global</emphasis>
namespace may need to be selected if the user wants to specify an absolute path. If
any path element of the namespace does not exist, it is created.
</para>
<para>
The change will be immediately visible across all references to the function
(including in any Decompiler, Listing, and Functions windows).
</para>
</sect2>
<sect2 id="ActionRenameField">
<title>Rename Field</title>
<para>
Rename the field currently under the cursor within its <emphasis>structure</emphasis>
data-type definition.
</para>
<para>
The action brings up a dialog prepopulated with the
current name of the field. Editing and confirming this dialog immediately changes the
field's name in its corresponding structure definition. The dialog enforces unique field names.
</para>
<para>
If the initial name looks like <code>field_0x..</code>, it may be that the field offset was
discovered by the Decompiler, and the field does not exist in the structure definition.
In this case, a new field is created at that offset, with the new name and a data-type of
<emphasis role="bold">undefined</emphasis>.
</para>
<para>
The change to the definition is visible globally
throughout the Program, anywhere the data-type is referenced. Decompilation
is triggered again to incorporate the new name, but the output is otherwise unaffected.
</para>
<para>
Within a Decompiler window, field name tokens are presented <emphasis>in context</emphasis>,
showing how they are used within the code flow of the current function.
Combined with <xref linkend="ActionAutoStructure"/> and
<xref linkend="ActionRetypeField"/>, this action allows a
<emphasis>structure</emphasis> to be created and filled in based on this context.
</para>
</sect2>
<sect2 id="ActionRenameGlobal">
<title>Rename Global</title>
<para>
Rename the global variable corresponding to the token under the cursor.
</para>
<para>
This action brings up a dialog containing a text field prepopulated with the
current name of the variable. The current namespace (and any parent namespaces) is
presented in a drop-down menu. Editing the text field changes the <emphasis>base</emphasis>
name of the variable, and selecting within the drop-down menu allows
the variable to be moved into a parent namespace.
</para>
<para>
A new or child namespace can
be specified by prepending the base name with the namespace using the C++ "::"
delimiter characters. Any namespace path entered this way is considered relative
to the namespace set in the drop-down menu, so the <emphasis role="bold">Global</emphasis>
namespace may need to be selected if the user wants to specify an absolute path. If
any path element of the namespace does not exist, it is created.
</para>
<para>
The change will be immediately visible across all references to the variable,
including in Decompiler and Listing windows. A new decompilation is triggered
to incorporate the new name, but the output is otherwise unaffected.
</para>
</sect2>
<sect2 id="ActionRenameLabel">
<title>Rename Label</title>
<para>
Rename the label corresponding to the token under the cursor.
</para>
<para>
A label can be renamed by triggering this action while the corresponding label token is
under the cursor. This action brings up the
<link xlink:href="help/topics/LabelMgrPlugin/Labels.htm#AddEditDialog">Edit Label Dialog</link>.
</para>
<para>
The change will be immediately visible across all references to the label
(including in any Decompiler, Listing, and Functions windows).
</para>
</sect2>
<sect2 id="ActionRenameVariable">
<title>Rename Variable</title>
<para>
Rename the local variable or parameter currently under the cursor.
</para>
<para>
The action brings up a dialog prepopulated with the current name of the variable.
Editing and confirming this dialog immediately changes the name, unless there is a
conflict with another variable.
</para>
<para>
Decompilation is triggered again to incorporate the
new name, causing local variable declarations to be reordered and line breaks to
change, but otherwise the output is unaffected.
</para>
<para>
Local variables and parameters presented by the Decompiler may be invented on-the-fly
and don't necessarily have a formal annotation in Ghidra
(see <xref linkend="AnnoteVariables"/>). Performing this action on
a variable will create an annotation if one didn't exist previously, which will
generally be visible as part of the function header in any Listing window.
A new annotation will <emphasis>not</emphasis> commit the data-type of the variable,
and data-types applied later, and elsewhere in the function, can still propagate into
the variable.
</para>
<para>
Performing this action on a function parameter causes a formal annotation to be created
for <emphasis>all</emphasis> parameters, although the names of any other parameters
will not be changed.
</para>
</sect2>
<sect2 id="ActionRetypeField">
<title>Retype Field</title>
<para>
Change the data-type of the field currently under the cursor within its
<emphasis>structure</emphasis> data-type definition.
</para>
<para>
The action brings up a dialog prepopulated with the current data-type associated
with the field. The user can select any fixed length data-type in the Program,
although selecting a larger data-type may cause an error if there is not enough room
for it with other existing fields.
Editing and confirming this dialog immediately changes the
corresponding data-type definition.
</para>
<para>
The change to the definition is visible globally throughout the Program,
anywhere the data-type is referenced, and is <emphasis>forcing</emphasis>
on the Decompiler (see <xref linkend="AnnoteForcing"/>). Decompilation is triggered
again, and the new data-type is propagated from the point of the field reference(s).
Changes to the output may be large and indirect.
</para>
</sect2>
<sect2 id="ActionRetypeGlobal">
<title>Retype Global</title>
<para>
Change the data-type of the global variable currently under the cursor.
</para>
<para>
This action brings up a dialog prepopulated with the current data-type of the variable.
The user can select any fixed length data-type in the Program that matches
the size of the variable. Editing and confirming this dialog immediately changes
the data-type.
</para>
<para>
The change is visible globally throughout the Program, anywhere the variable is
referenced, and is <emphasis>forcing</emphasis> on the Decompiler
(see <xref linkend="AnnoteForcing"/>). Decompilation is triggered
again, and the new data-type is propagated from the variable reference(s).
Changes to the output may be large and indirect.
</para>
</sect2>
<sect2 id="ActionRetypeReturn">
<title>Retype Return</title>
<para>
Change the data-type of the current function's <emphasis>return value</emphasis>.
</para>
<para>
This action is only available from the data-type token in the function declaration, at the
top of the Decompiler's output. It brings up a dialog prepopulated with the current
data-type returned by the function. The user can select any fixed length data-type in the Program.
Editing and confirming this dialog immediately changes the data-type. If an annotation for
the return value (named <code><RETURN></code>) did not exist previously, one is created.
</para>
<para>
As input parameter annotations and the return value annotation must be committed as a whole
(see the discussion of function prototype's in <xref linkend="AnnoteForcing"/>), if
no prototype existed previously, this action also causes variable annotations for all
input parameters to be created as well. In this situation, the action is equivalent to
<xref linkend="ActionCommitParams"/>, and a confirmation dialog comes up to notify the user.
</para>
<para>
Setting a data-type on the return value using this action affects decompilation for the
function itself and, additionally, any function that calls this function. Within a calling
function, the Decompiler propagates the data-type into the variable or expression incorporating
the return value at each call site.
</para>
</sect2>
<sect2 id="ActionRetypeVariable">
<title>Retype Variable</title>
<para>
Change the data-type of the local variable or parameter currently under the cursor.
</para>
<para>
This action brings up a dialog prepopulated with the current data-type of the variable.
The user can select any fixed length data-type in the Program that matches
the size of the variable. Editing and confirming this dialog immediately changes
the data-type.
</para>
<para>
The change to the data-type is <emphasis>forcing</emphasis> on the Decompiler
(see <xref linkend="AnnoteForcing"/>). Decompilation is triggered again, and the new
data-type is propagated from the variable reference(s). Changes to the output may be
large and indirect.
</para>
<para>
Local variables and parameters presented by the Decompiler may be invented on-the-fly
and don't necessarily have a formal annotation in Ghidra
(see <xref linkend="AnnoteVariables"/>). Performing this action on a variable
will create an annotation if one didn't exist previously, which will generally be
visible as part of the function header in any Listing window.
</para>
<para>
Performing this action on a function parameter causes a formal annotation to
be created for <emphasis>all</emphasis> parameters to the function, and the number
of parameters and their memory locations become fixed. If the annotation of another
parameter did not exist previously, then its data-type is <emphasis>not</emphasis>
forced by this action.
</para>
<para>
Data-type information applied to parameters using this action is especially impactful
because it affects decompilation for the function owning the parameter and, additionally,
any function that calls this owning function.
</para>
</sect2>
<sect2 id="ActionSetEquate">
<title>Set Equate...</title>
<para>
Change the display of the integer or character constant under the cursor to an <emphasis>equate</emphasis>
string.
</para>
<para>
An equate is a descriptive string associated with a specific constant value, which is managed globally for
a Program by the Equate plug-in (See <link xlink:href="help/topics/EquatePlugin/Equates.htm">Equates</link>).
</para>
<para>
The <emphasis role="bold">Set Equate</emphasis> command, brings up a dialog listing other equates
that have previously been associated with the selected constant. The user can choose an equate from this list
or define a new equate for the constant by typing in the text field at the top of the dialog. Alternately,
the text field can be used as a filter to narrow down possibilities prior to selecting from the list. Clicking
OK, completes the action, and the selected equate is substituted for its constant.
</para>
<para>
This command primarily targets a constant token in a Decompiler window, but
if there is a <emphasis>scalar</emphasis> operand in an instruction that corresponds
with the selected constant, the same equate is also applied to the scalar in any Listing
window. This is equivalent to selecting the
<link xlink:href="help/topics/EquatePlugin/Equates.htm#Set_Equate">Set Equate</link> command from a
Listing window. There may not be a scalar operand directly corresponding to the selected constant, in
which case the equate will be applied only in the Decompiler window.
</para>
<para>
Once an equate is applied, the constant can be returned to its <emphasis>default</emphasis> display
by selecting the <xref linkend="ActionRemoveEquate"/> command.
</para>
</sect2>
<sect2 id="ActionIsolate">
<title>Split Out As New Variable</title>
<para>
Split a high-level variable so that the selected token becomes a new variable with the smallest
possible range.
</para>
<para>
The Decompiler defines high-level variables in terms of <link linkend="ConceptVarnode">varnodes</link> that
are merged together to produce the final variable. Some merging is speculative, which reduces the
number of variables overall, but is not strictly necessary for valid decompilation. The merged
variable can be represented with two or more variables that have a smaller range (see the
documentation on <xref linkend="ConceptHighVariable"/>).
</para>
<para>
This command is only available if the selected token is part of a high-level variable that has
been speculatively merged. The part of the variable that is directly represented by the
token is split out as its own variable, retaining the name of the original variable.
Any other pieces become a separate variable with a new name.
</para>
</sect2>
</section>
</chapter>
</book>