diff --git a/Ghidra/Features/Decompiler/build.gradle b/Ghidra/Features/Decompiler/build.gradle index e84cca09d2..d3725115d5 100644 --- a/Ghidra/Features/Decompiler/build.gradle +++ b/Ghidra/Features/Decompiler/build.gradle @@ -93,7 +93,8 @@ task buildDecompilerHelpHtml(type: Exec) { echo '** Building html files **' xsltproc --output $buildDir/decomp_noscaling.xml --stringparam profile.condition "noscaling" /usr/share/sgml/docbook/xsl-stylesheets/profiling/profile.xsl decompileplugin.xml 2>&1 xsltproc --stringparam base.dir ${installHelpPoint}/topics/DecompilePlugin/ --stringparam root.filename Decompiler decompileplugin_html.xsl $buildDir/decomp_noscaling.xml 2>&1 - sed -i -e '/Frontpage.css/ { p; s/Frontpage.css/languages.css/; }' ${installHelpPoint}/topics/DecompilePlugin/*.html + rm ${installHelpPoint}/topics/DecompilePlugin/Decompiler.html + sed -i -e '/Frontpage.css/ { p; s/Frontpage.css/languages.css/; }' ${installHelpPoint}/topics/DecompilePlugin/*.html 2>&1 echo '** Done. **' """ diff --git a/Ghidra/Features/Decompiler/src/main/doc/decompileplugin.xml b/Ghidra/Features/Decompiler/src/main/doc/decompileplugin.xml index 48dcc113e4..dd328c7f7a 100644 --- a/Ghidra/Features/Decompiler/src/main/doc/decompileplugin.xml +++ b/Ghidra/Features/Decompiler/src/main/doc/decompileplugin.xml @@ -976,7 +976,7 @@ 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 + 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 first use point @@ -1107,7 +1107,7 @@ Killed by Call - In constrast to unaffected memory locations, a prototype model may specify + In contrast to unaffected memory locations, a prototype model may specify killed by call locations that are guaranteed not to be used to hold a value across the function. @@ -1150,7 +1150,7 @@ A function body is the set of addresses reached by control-flow analysis (and the machine instructions at those addresses). - + Entry Point The entry point address for a function plays a pivotal role for @@ -1171,7 +1171,7 @@ (See Create Function) - + Formal Function Body When a function is created, Ghidra stores its function body as a set of addresses in the @@ -1181,17 +1181,17 @@ in particular use the formal function body to know which function to decompile in response to a navigation event to an arbitrary address. - + The decompiler does not 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. - + - + Flow Overrides Control-flow behavior for machine instructions is generally determined by the underlying @@ -1339,12 +1339,12 @@ types can be configured to display in decompiler output, by changing the decompiler Display options (See ). - + Unlike the 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. - + @@ -1514,7 +1514,7 @@ Local variables, - in constrast, do not generally exist across the whole function, but come into scope + 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. @@ -1607,7 +1607,7 @@ Character - ASCII or unicode encoded character data-types are supported for sizes of 1, 2, and 4. The size affectively + ASCII or 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 char and wchar_t are mapped to one of these sizes based on the @@ -1637,7 +1637,7 @@ Strings should be fully rendered in decompiler output, - with non-printable characters escaped using either traditional sequences like '\r', '\n' or using unicode + with non-printable characters escaped using either traditional sequences like '\r', '\n' or using Unicode escape sequences like '\xFF'. @@ -1689,7 +1689,7 @@ single value in the enumeration definition, the decompiler attempts to build a matching value by or-ing together multiple labels. The decompiler can be made to break out constants representing packed flags, - for instance, by labeling individal bit values within an enumeration. + for instance, by labeling individual bit values within an enumeration. @@ -1760,12 +1760,12 @@ 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. - + 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. - + The major exception to forcing annotations is if the data-type in the annotation is undefined. Ghidra reserves the following names to represent formally undefined data-types: @@ -1992,7 +1992,7 @@ Variable Arguments - Functions have a boolean property called variable argments, which can be turned on + Functions have a boolean property called variable arguments, 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 variable arguments function, allowing @@ -2056,11 +2056,11 @@ See the complete discussion in . But keep in mind: - + The input parameters and return value are all forced on the decompiler as a unit based on the Signature Source-Type. They are all forced if the Source-Type is set to anything other than DEFAULT; otherwise none of them are forced. - + If the function prototype's annotations are not forced, the decompiler will attempt to discover the parameters and return value using the calling convention. The prototype model underlying the calling convention @@ -2507,7 +2507,7 @@ 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 + listed above. This includes delimiter characters like commas and parentheses as well as various operator characters. @@ -2644,7 +2644,7 @@ 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 + of the output. The decompiler generates these comments, independent of those laid down by users, to indicate unusual conditions or possible errors (See ). @@ -2866,13 +2866,13 @@ Comment tokens map to the machine address associated with the comment. - + 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. - + @@ -2950,13 +2950,13 @@ Triggers a re-decompilation of the current function displayed in the window. Any cached results are discarded, and a full decompile is performed. - + This action is not necessary for normal reverse engineering tasks. Re-decompilation is automatically 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 a primarily a debugging aid for plug-in developers. - + @@ -2996,9 +2996,9 @@ Generate a control-flow graph based upon the results in the active Decompiler Window, and render it using the current Graph Service. - + If no Graph Service is available then this action will no be present. - + @@ -3586,7 +3586,7 @@ A new or child namespace can be specified by prepending the base name with the namespace using the C++ '::' separator characters. Any namespace path entered this way is considered relative - to the namespace set in the drop-down meu, so the Global + to the namespace set in the drop-down menu, so the Global 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. @@ -3642,7 +3642,7 @@ A new or child namespace can be specified by prepending the base name with the namespace using the C++ '::' separator characters. Any namespace path entered this way is considered relative - to the namespace set in the drop-down meu, so the Global + to the namespace set in the drop-down menu, so the Global 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. @@ -3741,7 +3741,7 @@ the return value (named <RETURN>) did not exist previously, one is created. - As input parameter annotations and the return value annotation must be commited as a whole + As input parameter annotations and the return value annotation must be committed as a whole (see the discussion of function prototype's in ), 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 diff --git a/Ghidra/Features/Decompiler/src/main/doc/decompileplugin_html.xsl b/Ghidra/Features/Decompiler/src/main/doc/decompileplugin_html.xsl index c714eb520b..b15f1d6dd0 100644 --- a/Ghidra/Features/Decompiler/src/main/doc/decompileplugin_html.xsl +++ b/Ghidra/Features/Decompiler/src/main/doc/decompileplugin_html.xsl @@ -40,6 +40,8 @@ + + diff --git a/Ghidra/Features/Decompiler/src/main/help/help/TOC_Source.xml b/Ghidra/Features/Decompiler/src/main/help/help/TOC_Source.xml index a5b016054e..73e9359197 100644 --- a/Ghidra/Features/Decompiler/src/main/help/help/TOC_Source.xml +++ b/Ghidra/Features/Decompiler/src/main/help/help/TOC_Source.xml @@ -68,7 +68,8 @@ text="Program Annotations Affecting the Decompiler" target="help/topics/DecompilePlugin/DecompilerAnnotations.html"> - + + diff --git a/Ghidra/Features/Decompiler/src/main/help/help/topics/DecompilePlugin/Decompiler.html b/Ghidra/Features/Decompiler/src/main/help/help/topics/DecompilePlugin/Decompiler.html deleted file mode 100644 index e4ca3b09aa..0000000000 --- a/Ghidra/Features/Decompiler/src/main/help/help/topics/DecompilePlugin/Decompiler.html +++ /dev/null @@ -1,59 +0,0 @@ - - - -Decompiler - - - - - - - -
- - - - - - - -
Decompiler
   Next -
-
-
-
-
-

-Decompiler

-
-
- - - - - - - - - - - -
-
-
- - - - - - - - - - - -
   Next -
   Decompiler
-
- - diff --git a/Ghidra/Features/Decompiler/src/main/help/help/topics/DecompilePlugin/DecompilerAnnotations.html b/Ghidra/Features/Decompiler/src/main/help/help/topics/DecompilePlugin/DecompilerAnnotations.html index 4f613be70c..04aecdc6c7 100644 --- a/Ghidra/Features/Decompiler/src/main/help/help/topics/DecompilePlugin/DecompilerAnnotations.html +++ b/Ghidra/Features/Decompiler/src/main/help/help/topics/DecompilePlugin/DecompilerAnnotations.html @@ -10,21 +10,7 @@ - -
- - - - - - - -
Program Annotations Affecting the Decompiler
-Prev   Next -
-
-
-
+

Program Annotations Affecting the Decompiler

@@ -63,7 +49,7 @@

-Entry Point

+Entry Point

The entry point address for a function plays a pivotal role for @@ -86,7 +72,7 @@

-Formal Function Body

+Formal Function Body

When a function is created, Ghidra stores its function body as a set of addresses in the @@ -96,9 +82,9 @@ in particular use the formal function body to know which function to decompile in response to a navigation event to an arbitrary address.

-
+
- +
[Note][Warning]
@@ -114,7 +100,7 @@

-Flow Overrides

+Flow Overrides

Control-flow behavior for machine instructions is generally determined by the underlying @@ -261,9 +247,9 @@ types can be configured to display in decompiler output, by changing the decompiler Display options (See Display <kind-of> Comments).

-
+
- +
[Note][Warning]
@@ -459,7 +445,7 @@

Local variables, - in constrast, do not generally exist across the whole function, but come into scope + 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. @@ -568,7 +554,7 @@ Character

- ASCII or unicode encoded character data-types are supported for sizes of 1, 2, and 4. The size affectively + ASCII or 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 char and wchar_t are mapped to one of these sizes based on the @@ -602,7 +588,7 @@

Strings should be fully rendered in decompiler output, - with non-printable characters escaped using either traditional sequences like '\r', '\n' or using unicode + with non-printable characters escaped using either traditional sequences like '\r', '\n' or using Unicode escape sequences like '\xFF'.

@@ -662,7 +648,7 @@ single value in the enumeration definition, the decompiler attempts to build a matching value by or-ing together multiple labels. The decompiler can be made to break out constants representing packed flags, - for instance, by labeling individal bit values within an enumeration. + for instance, by labeling individual bit values within an enumeration.

@@ -741,9 +727,9 @@ 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.

-
+
- +
[Note][Warning]
@@ -799,7 +785,7 @@

- +
[Note][Note]
@@ -998,7 +984,7 @@
Variable Arguments

- Functions have a boolean property called variable argments, which can be turned on + Functions have a boolean property called variable arguments, 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 variable arguments function, allowing @@ -1058,9 +1044,9 @@ See the complete discussion in “Forcing Data-types”. But keep in mind:

-
+
- +
[Note][Warning]
@@ -1268,23 +1254,5 @@

- -
-
- - - - - - - - - - - -
-Prev   Next -
Decompiler Concepts Home Decompiler Options
-
- + diff --git a/Ghidra/Features/Decompiler/src/main/help/help/topics/DecompilePlugin/DecompilerConcepts.html b/Ghidra/Features/Decompiler/src/main/help/help/topics/DecompilePlugin/DecompilerConcepts.html index 07f0db5714..e3ca5715c0 100644 --- a/Ghidra/Features/Decompiler/src/main/help/help/topics/DecompilePlugin/DecompilerConcepts.html +++ b/Ghidra/Features/Decompiler/src/main/help/help/topics/DecompilePlugin/DecompilerConcepts.html @@ -10,21 +10,7 @@ - -
- - - - - - - -
Decompiler Concepts
-Prev   Next -
-
-
-
+

Decompiler Concepts

@@ -911,7 +897,7 @@

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 + 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 first use point @@ -1054,7 +1040,7 @@ Killed by Call

- In constrast to unaffected memory locations, a prototype model may specify + In contrast to unaffected memory locations, a prototype model may specify killed by call locations that are guaranteed not to be used to hold a value across the function.

@@ -1062,23 +1048,5 @@ - -
-
- - - - - - - - - - - -
-Prev   Next -
Decompiler Home Program Annotations Affecting the Decompiler
-
- + diff --git a/Ghidra/Features/Decompiler/src/main/help/help/topics/DecompilePlugin/DecompilerIntro.html b/Ghidra/Features/Decompiler/src/main/help/help/topics/DecompilePlugin/DecompilerIntro.html index 8ed405d946..0e81f563c4 100644 --- a/Ghidra/Features/Decompiler/src/main/help/help/topics/DecompilePlugin/DecompilerIntro.html +++ b/Ghidra/Features/Decompiler/src/main/help/help/topics/DecompilePlugin/DecompilerIntro.html @@ -10,21 +10,7 @@ - -
- - - - - - - -
Decompiler
-Prev   Next -
-
-
-
+

Decompiler

@@ -164,23 +150,5 @@

- -
-
- - - - - - - - - - - -
-Prev   Next -
Decompiler Home Decompiler Concepts
-
- + diff --git a/Ghidra/Features/Decompiler/src/main/help/help/topics/DecompilePlugin/DecompilerOptions.html b/Ghidra/Features/Decompiler/src/main/help/help/topics/DecompilePlugin/DecompilerOptions.html index efc2897d14..c819051aeb 100644 --- a/Ghidra/Features/Decompiler/src/main/help/help/topics/DecompilePlugin/DecompilerOptions.html +++ b/Ghidra/Features/Decompiler/src/main/help/help/topics/DecompilePlugin/DecompilerOptions.html @@ -10,21 +10,7 @@ - -
- - - - - - - -
Decompiler Options
-Prev   Next -
-
-
-
+

Decompiler Options

@@ -299,7 +285,7 @@

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 + listed above. This includes delimiter characters like commas and parentheses as well as various operator characters.

@@ -422,7 +408,7 @@

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 + of the output. The decompiler generates these comments, independent of those laid down by users, to indicate unusual conditions or possible errors (See “Warning Comments”).

@@ -530,23 +516,5 @@

-
-
-
- - - - - - - - - - - -
-Prev   Next -
Program Annotations Affecting the Decompiler Home Decompiler Window
-
- + diff --git a/Ghidra/Features/Decompiler/src/main/help/help/topics/DecompilePlugin/DecompilerWindow.html b/Ghidra/Features/Decompiler/src/main/help/help/topics/DecompilePlugin/DecompilerWindow.html index d4795ab6a3..e9e316855a 100644 --- a/Ghidra/Features/Decompiler/src/main/help/help/topics/DecompilePlugin/DecompilerWindow.html +++ b/Ghidra/Features/Decompiler/src/main/help/help/topics/DecompilePlugin/DecompilerWindow.html @@ -9,20 +9,7 @@ - -
- - - - - - - -
Decompiler Window
-Prev   
-
-
-
+

Decompiler Window

@@ -100,7 +87,7 @@

Initially pushing or selecting - Decompile from Window menu in the tool + Decompile from the Window menu in the tool brings up the main window. The main window always displays the function at the current address 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 @@ -137,9 +124,9 @@

Comment tokens map to the machine address associated with the comment.

-
+
- +
[Note][Warning]
@@ -242,9 +229,9 @@ Triggers a re-decompilation of the current function displayed in the window. Any cached results are discarded, and a full decompile is performed.

-
+
- +
[Note][Tip]
@@ -300,9 +287,9 @@ Generate a control-flow graph based upon the results in the active Decompiler Window, and render it using the current Graph Service.

-
+
- +
[Note][Warning]
@@ -684,13 +671,22 @@
Def-Use
-

+

+

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

+

+

+ In the following example, the token representing the first write to the + variable a is selected when Def-Use is chosen. +

+
+

+

+
Forward Slice

@@ -898,7 +894,7 @@ A new or child namespace can be specified by prepending the base name with the namespace using the C++ '::' separator characters. Any namespace path entered this way is considered relative - to the namespace set in the drop-down meu, so the Global + to the namespace set in the drop-down menu, so the Global 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.

@@ -958,7 +954,7 @@ A new or child namespace can be specified by prepending the base name with the namespace using the C++ '::' separator characters. Any namespace path entered this way is considered relative - to the namespace set in the drop-down meu, so the Global + to the namespace set in the drop-down menu, so the Global 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.

@@ -1065,7 +1061,7 @@ the return value (named <RETURN>) did not exist previously, one is created.

- As input parameter annotations and the return value annotation must be commited as a whole + As input parameter annotations and the return value annotation must be committed as a whole (see the discussion of function prototype's in “Forcing Data-types”), 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 @@ -1133,22 +1129,5 @@

-
-
-
- - - - - - - - - - - -
-Prev   
Decompiler Options Home 
-
- + diff --git a/Ghidra/Features/SourceCodeLookup/src/main/help/help/topics/SourceCodeLookupPlugin/Source_Code_Lookup.html b/Ghidra/Features/SourceCodeLookup/src/main/help/help/topics/SourceCodeLookupPlugin/Source_Code_Lookup.html index bf61aadf08..0f7755b4de 100644 --- a/Ghidra/Features/SourceCodeLookup/src/main/help/help/topics/SourceCodeLookupPlugin/Source_Code_Lookup.html +++ b/Ghidra/Features/SourceCodeLookup/src/main/help/help/topics/SourceCodeLookupPlugin/Source_Code_Lookup.html @@ -66,7 +66,7 @@ "help/topics/CodeBrowserPlugin/CodeBrowser.htm">Listing cursor on the symbol you want to lookup and choose from the menu Navigation → Go To Symbol Source.

You can also execute this action when your cursor is in the Decompiler.

+ "help/topics/DecompilePlugin/DecompilerIntro.html">Decompiler.

Troubleshooting