diff --git a/Ghidra/Features/Decompiler/src/main/doc/decompileplugin.xml b/Ghidra/Features/Decompiler/src/main/doc/decompileplugin.xml
index 7f32a1b340..0af41c4ab4 100644
--- a/Ghidra/Features/Decompiler/src/main/doc/decompileplugin.xml
+++ b/Ghidra/Features/Decompiler/src/main/doc/decompileplugin.xml
@@ -135,7 +135,7 @@
- Concepts
+ Decompiler Concepts
P-code
@@ -873,15 +873,16 @@
+
-
- The HighFunction
-
- A HighFunction 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:
-
+
+ The HighFunction
+
+ A HighFunction 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:
+
A control-flow representation of the function
@@ -895,19 +896,19 @@
A symbol-table of variables accessed by the function.
-
-
-
- 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 HighFunction, HighVariable, and
- HighSymbol refer to this decompiler specific view of the function.
-
+
+
+
+ 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 HighFunction, HighVariable, and
+ HighSymbol refer to this decompiler specific view of the function.
+
-
- HighSymbol
-
+
+ HighSymbol
+
A HighSymbol is one of the explicit symbols recovered by the
decompiler. It is made up of a name and data-type and can describe either:
@@ -923,8 +924,8 @@
-
-
+
+
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 @@
informed 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.
-
-
+
+
Various actions within Ghidra allow the user to commit
specific HighSymbols to the database as a permanent annotation, but this
does not happen by default.
-
-
-
-
- Varnodes in the Decompiler
-
- Varnodes are the central variable 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.
-
- 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 lifetime
- or scope within the function. The scope starts at:
-
+
+
+
+ Varnodes in the Decompiler
+
+ Varnodes are the central variable 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.
+
+
+ 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 lifetime
+ or scope within the function. The scope starts at:
+
@@ -973,54 +974,54 @@
-
- The scope extends via control-flow to each p-code operation that reads 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 first use point
- or first use offset.
-
+
+ The scope extends via control-flow to each p-code operation that reads 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 first use point
+ or first use offset.
+
+
+ In the decompiler output for a specific high-level language like C or Java,
+ a varnode still has a scope 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.
+
+
+
+
+ HighVariable
- In the decompiler output for a specific high-level language like C or Java,
- a varnode still has a scope 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.
-
-
-
-
- HighVariable
-
A HighVariable 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.
-
-
+
+
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.
-
-
+
+
A HighVariable always describes explicit 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.
-
-
+
+
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.
-
+
-
+
Merging
Merging 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 ).
-
@@ -1885,7 +1885,7 @@
affecting the engine behavior
affecting the decompiler's transformation process
- affecting the final presentation of decompiler output
+ affecting the final presentation of decompiler output
@@ -1900,6 +1900,10 @@
General Options
+
+ 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.
+
@@ -1948,6 +1952,10 @@
Analysis Options
+
+ These options directly affect how the decompiler performs its analysis, either by
+ toggling specific analysis passes or changing how it treats various annotations.
+
@@ -2063,7 +2071,7 @@
Simplify predication
- When this option is active, the decompiler simplifies codes sequences containing
+ When this option is active, the decompiler simplifies code sequences containing
predicated instructions. A predicated instruction is executed
conditionally based on a boolean value, the predicate,
and a sequence of instructions can share the same predicate. The decompiler merges the
@@ -2085,6 +2093,302 @@
+
+
+ Display Options
+
+ These options do not change the decompiler's analysis but only affect how the results are presented.
+
+
+
+
+
+
+ Background Color
+
+
+ Assign the background color for the Decompiler window.
+
+
+
+
+ Color for <token>
+
+
+ Assign colors to the different types of language tokens emitted by the decompiler.
+ These include:
+
+
+ Comments
+ Constants - including integer, floating-point, character, and string
+ Functions names
+ Globals - names of variables with global scope
+ Keywords - reserved names in the language being emitted
+ Parameters - names of function input variables
+ Types - names of data-types in variable declarations and casts
+ Variables - names of local variables
+
+
+
+
+
+
+ Color Default
+
+
+ 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 operator
+ characters.
+
+
+
+
+ Color for Current Variable Highlight
+
+
+ Assign the background color used to highlight the token currently under the cursor in a Decompiler Window.
+
+
+
+
+ Color for Highlighting Find Matches
+
+
+ Assign the background color used to highlight characters matching the current Find pattern.
+ See .
+
+
+
+
+ Comment line indent level
+
+
+ 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.
+
+
+
+
+ Comment style
+
+
+ Set the language syntax used to delimit comments emitted as part of decompiler output. For C and Java,
+ the choices are /* C style comments */ and // C++ style comments.
+
+
+
+
+ Disable printing of type casts
+
+
+ Set whether the syntax for type casts 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.
+
+
+
+
+ Display <kind-of> Comments
+
+
+ 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 .
+ Each kind of comment has its own toggle and can be individually included or excluded from decompiler output.
+
+
+
+ PLATE - Whether plate comments within the body of the function are displayed
+
+
+ PRE
+
+
+ POST
+
+
+ EOL
+
+
+
+
+
+
+
+ Display Header comment
+
+
+ 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 entry point of the
+ function. See the discussion in .
+ The inclusion of other Plate comments is controlled by the Display PLATE comments toggle, described above.
+
+
+
+
+ Display Line Numbers
+
+
+ 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.
+
+
+
+
+ Display Namespaces
+
+
+ Control how the decompiler displays namespace information associated
+ with function and variable symbols. The possible settings are:
+
+
+
+ Always - Always display the entire namespace path
+
+
+ Never - Never display the namespace path
+
+
+ Minimally - Display the minimal path that distinguishes the symbol
+
+
+
+
+
+ The Minimally 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.
+
+
+ The Never setting never displays any of the namespace path under any
+ circumstances and may produce output that is ambiguous and doesn't formally parse.
+
+
+
+
+ Display Warning comments
+
+
+ Toggle whether decompiler generated WARNING 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 ).
+
+
+
+
+ Font
+
+
+ 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.
+
+
+
+
+ Integer format
+
+
+ Set how integer constants are formatted in the decompiler output.
+ The possible settings are:
+
+
+
+ Best Fit - Select the most natural representation
+
+
+ Force Decimal - Always use a decimal representation
+
+
+ Force Hexadecimal - Always use a hexadecimal representation
+
+
+
+ For Best Fit, a representation is selected based on how
+ close it is to either a round decimal value (10, 100, 1000, etc.) or
+ a round hexadecimal value (0x10, 0x100, 0x1000, etc.)
+
+
+
+
+ Maximum characters in a code line
+
+
+ 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.
+
+
+
+
+ Number of characters per indent level
+
+
+ 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, if/else bodies, etc.)
+ bodies adds this number characters.
+
+
+
+
+ Print 'NULL' for null pointers
+
+
+ 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 null pointer)
+ using the special token NULL. Otherwise the pointer value is represented with the '0' character,
+ which is then type cast into a pointer.
+
+
+
+
+ Print calling convention name
+
+
+ Set whether the calling convention 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 .
+
+
+
+
+
+
+
+
+
+ Program Options
+
+ Changes to these options affect only the current Program being analyzed.
+
+
+
+
+
+
+ Prototype Evaluation
+
+
+ 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, __stdcall, __thiscall etc. See the
+ discussion in .
+
+
+
+
+
+
+
+