<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE book [
<!ENTITY emsp    "&#x2003;"> <!-- Embedded space -->
<!ENTITY nbsp    "&#xA0;">   <!-- 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>&nbsp;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>&lt;</code> or <code>&gt;</code></td>
	    <td>True if one varnode is less than the other as unsigned integers.</td>
	  </tr>
	  <tr>
	    <td>INT_SLESS</td>
	    <td><code>&lt;</code> or <code>&gt;</code></td>
	    <td>True if one varnode is less than the other as signed integers.</td>
	  </tr>
	  <tr>
	    <td>INT_LESSEQUAL</td>
	    <td><code>&lt;=</code> or <code>&gt;=</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>&lt;=</code> or <code>&gt;=</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>&amp;</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>&lt;&lt;</code></td>
	    <td>Left shift.</td>
	  </tr>
	  <tr>
	    <td>INT_RIGHT</td>
	    <td><code>&gt;&gt;</code></td>
	    <td>Unsigned (logical) right shift.</td>
	  </tr>
	  <tr>
	    <td>INT_SRIGHT</td>
	    <td><code>&gt;&gt;</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>&amp;&amp;</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>&lt;</code> or <code>&gt;</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>&lt;=</code> or <code>&gt;=</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>&lt;na&gt;</code></td>
	    <td>Convert integer to floating-point.</td>
	  </tr>
	  <tr>
	    <td>FLOAT2FLOAT</td>
	    <td><code>&lt;na&gt;</code></td>
	    <td>Convert between different floating-point precisions.</td>
	  </tr>
	  <tr>
	    <td>TRUNC</td>
	    <td><code>&lt;na&gt;</code></td>
	    <td>Convert floating-point to integer.</td>
	  </tr>
	  <tr>
	    <td>CPOOLREF</td>
	    <td><code>&lt;na&gt;</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>&lt;na></code></td>
	    <td>Compiler phi-node: merge values from multiple control-flow paths.</td>
	  </tr>
	  <tr>
	    <td>INDIRECT</td>
	    <td><code>&lt;na></code></td>
	    <td>Indirect effect on a varnode.</td>
	  </tr>
	  <tr>
	    <td>CAST</td>
	    <td><code>&lt;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>&lt;na></code></td>
	    <td>Insert a bit-range.</td>
	  </tr>
	  <tr>
	    <td>EXTRACT</td>
	    <td><code>&lt;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>&lt;Root&gt;/Ghidra/Processors/&lt;Family&gt;/data/languages</code>
    </informalexample>
    where <code>&lt;Root&gt;</code> represents the root directory of the Ghidra installation and
    <code>&lt;Family&gt;</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>&lt;prototype&gt; - describing a specific calling convention</listitem>
	      <listitem>&lt;callfixup&gt; - describing a Call-fixup</listitem>
	      <listitem>&lt;callotherfixup&gt; - 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) &gt;&gt; 3) &amp; 7
	      struct1.bit1 = i;         //  struct1._0_1 = ((i &amp; 7) &lt;&lt; 3) | (struct1._0_1 &amp; 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>-&gt;</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>&lt;RETURN&gt;</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>
	  &emsp;<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>&nbsp;<emphasis>Analysis</emphasis> - lists <xref linkend="AnalysisOptions"/> that affect the Decompiler's transformation process.
	</listitem>
	<listitem>
	  &emsp;<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>&nbsp;<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 &lt;program&gt;...</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>&lt;</code>, <code>&gt;</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 &lt; 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 &lt;&lt; 2 &amp; 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>&lt;&lt;=</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 &lt;kind-of&gt; 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 &amp; 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 &lt;token&gt;</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 &lt;kind-of&gt; 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>&lt;prototype&gt;</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>&lt;callfixup&gt;</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;
    ]]>]]&gt;<![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>&lt;callotherfixup&gt;</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;
    ]]>]]&gt;<![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>&lt;blank&gt;</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>&lt;prototype&gt;</code>, <code>&lt;callfixup&gt;</code>, or <code>&lt;callotherfixup&gt;</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>&nbsp;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>&nbsp;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>&nbsp;.
	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>&nbsp;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>&nbsp;
	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>&nbsp;- 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>&nbsp;- 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>&nbsp;- 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>&nbsp;- 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>&nbsp;- 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>&nbsp;- 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 &lt;data-type&gt;</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 &lt;function/global variable&gt;</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 &lt;address&gt;</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>&lt;RETURN&gt;</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>
