mirror/ghidra
1
0
Fork 0
mirror of https://github.com/NationalSecurityAgency/ghidra.git synced 2026-10-19 18:12:14 -09:00
Code Issues Packages Projects Releases Wiki Activity

documentation for display options

Browse Source
This commit is contained in:
caheckman
2020-08-28 17:20:15 -04:00
parent 31e712b993
commit 5ec5dcaa87
1 changed files with 379 additions and 75 deletions
Download Patch File Download Diff File Expand all files Collapse all files

454
Ghidra/Features/Decompiler/src/main/doc/decompileplugin.xml
View File

@@ -135,7 +135,7 @@
</chapter>
<chapter id="Decompiler_Concepts">
<title>Concepts</title>
<title>Decompiler Concepts</title>
<section id="pcode">
<title>P-code</title>
@@ -873,15 +873,16 @@
</informalexample>
</sect3>
</sect2>
</section>
<sect2 id="HighFunction">
<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>
<section id="HighFunction">
<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
@@ -895,19 +896,19 @@
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 view (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>
</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 view (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>
<sect3>
<title>HighSymbol</title>
<para>
<sect2>
<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>
@@ -923,8 +924,8 @@
</listitem>
</itemizedlist>
</informalexample>
</para>
<para>
</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
@@ -934,31 +935,31 @@
<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>
</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>
</sect3>
<sect3 id="VarnodeSSA">
<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>
</sect2>
<sect2 id="VarnodeSSA">
<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>
@@ -973,54 +974,54 @@
</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 definining 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>
</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 definining 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="HighVariable">
<title>HighVariable</title>
<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>
</sect3>
<sect3 id="HighVariable">
<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>
</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>
</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>
</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>
</para>
<sect4>
<sect3>
<title>Merging</title>
<para>
<emphasis role="bold">Merging</emphasis> is the part of the analysis process where
@@ -1046,7 +1047,6 @@
To a limited extent, users are able to control this kind of merging
(See <xref linkend="IsolateAction"/>).
</para>
</sect4>
</sect3>
</sect2>
</section>
@@ -1885,7 +1885,7 @@
<itemizedlist mark='bullet'>
<listitem><xref linkend="GeneralOptions"/> affecting the engine behavior</listitem>
<listitem><xref linkend="AnalysisOptions"/> affecting the decompiler's transformation process</listitem>
<listitem><xref linkend="DisplayOption"/> affecting the final presentation of decompiler output</listitem>
<listitem><xref linkend="DisplayOptions"/> affecting the final presentation of decompiler output</listitem>
</itemizedlist>
</informalexample>
</para>
@@ -1900,6 +1900,10 @@
</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>
@@ -1948,6 +1952,10 @@
<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>
@@ -2063,7 +2071,7 @@
<term><emphasis role="bold">Simplify predication</emphasis></term>
<listitem>
<para>
When this option is active, the decompiler simplifies codes sequences containing
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
@@ -2085,6 +2093,302 @@
</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>
<term><emphasis role="bold">Background Color</emphasis></term>
<listitem>
<para>
Assign the background color for the Decompiler window.
</para>
</listitem>
</varlistentry>
<varlistentry>
<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>
</itemizedlist>
</informalexample>
</para>
</listitem>
</varlistentry>
<varlistentry>
<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 above. This includes delimiter characters like commas and parantheses as well as various <emphasis>operator</emphasis>
characters.
</para>
</listitem>
</varlistentry>
<varlistentry>
<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>
<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="FindCommand"/>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<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>
<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>
<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>
<term><emphasis role="bold">Display &lt;kind-of&gt; Comments</emphasis></term>
<listitem>
<para>
Set whether a specific kind of comment can be incorporated into decompiler output. Comments in
Ghidra are categorized based on their placement within the Listing Window, and the decompiler
in general tries to display comments where appropriate. See the discussion in <xref linkend="AnnoteComments"/>.
Each kind of comment has its own toggle and can be individually included or excluded from decompiler output.
<informalexample>
<itemizedlist mark='bullet'>
<listitem>
<emphasis role="bold">PLATE</emphasis> - Whether plate comments <emphasis>within the body of the function</emphasis> are displayed
</listitem>
<listitem>
<emphasis role="bold">PRE</emphasis>
</listitem>
<listitem>
<emphasis role="bold">POST</emphasis>
</listitem>
<listitem>
<emphasis role="bold">EOL</emphasis>
</listitem>
</itemizedlist>
</informalexample>
</para>
</listitem>
</varlistentry>
<varlistentry>
<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>
<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>
<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">Always</emphasis> - Always display the entire namespace path
</listitem>
<listitem>
<emphasis role="bold">Never</emphasis> - Never display the namespace path
</listitem>
<listitem>
<emphasis role="bold">Minimally</emphasis> - Display the minimal path that distinguishes the symbol
</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>
<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 layed down by users, to
indicate unusual conditions or possible errors (See <xref linkend="WarningsErrors"/>).
</para>
</listitem>
</varlistentry>
<varlistentry>
<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 the system can be used. The size of
the font can also be controlled from this option.
</para>
</listitem>
</varlistentry>
<varlistentry>
<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">Best Fit</emphasis> - Select the most <emphasis>natural</emphasis> representation
</listitem>
<listitem>
<emphasis role="bold">Force Decimal</emphasis> - Always use a decimal representation
</listitem>
<listitem>
<emphasis role="bold">Force Hexadecimal</emphasis> - Always use a hexadecimal 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>
<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>
<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 (for function bodies,
loop bodies, <emphasis role="bold">if/else</emphasis> bodies, etc.)
bodies adds this number characters.
</para>
</listitem>
</varlistentry>
<varlistentry>
<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 type cast into a pointer.
</para>
</listitem>
</varlistentry>
<varlistentry>
<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="PrototypeModel"/>.
</para>
</listitem>
</varlistentry>
</variablelist>
</informalexample>
</para>
</section>
<section id="ProgramOptions">
<title>Program Options</title>
<para>
Changes to these options affect only the current Program being analyzed.
</para>
<para>
<informalexample>
<variablelist>
<?dbfo list-presentation="blocks"?>
<varlistentry>
<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 "unknown"). Many architectures have multiple
calling conventions, <code>__stdcall</code>, <code>__thiscall</code> etc. See the
discussion in <xref linkend="PrototypeModel"/>.
</para>
</listitem>
</varlistentry>
</variablelist>
</informalexample>
</para>
</section>
</chapter>
<chapter id="DecompilerWindow">