From 79df71dcdcabd4808057c3b60ddc6c3ddceec4ac Mon Sep 17 00:00:00 2001 From: caheckman <48068198+caheckman@users.noreply.github.com> Date: Thu, 3 Sep 2020 14:52:34 -0400 Subject: [PATCH] Most entries complete --- .../src/main/doc/decompileplugin.xml | 312 +++++++++++++++--- 1 file changed, 263 insertions(+), 49 deletions(-) diff --git a/Ghidra/Features/Decompiler/src/main/doc/decompileplugin.xml b/Ghidra/Features/Decompiler/src/main/doc/decompileplugin.xml index 558114516d..84a9fab409 100644 --- a/Ghidra/Features/Decompiler/src/main/doc/decompileplugin.xml +++ b/Ghidra/Features/Decompiler/src/main/doc/decompileplugin.xml @@ -4,7 +4,7 @@ Decompiler - + Decompiler @@ -134,10 +134,10 @@ - + Decompiler Concepts -
+
P-code P-code is Ghidra's Intermediate Representation (IR) language. When analyzing a function, @@ -146,7 +146,7 @@ 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". - + Address Space P-code defines all data in terms of an address space. An address space @@ -238,7 +238,7 @@ - + Varnodes A varnode is defined as a sequence of bytes in @@ -753,7 +753,7 @@ - + Internal Decompiler Functions Certain p-code operations can show up in decompiler output that cannot be represented @@ -875,7 +875,7 @@
-
+
The HighFunction A HighFunction is the collection of specific information @@ -943,7 +943,7 @@ - + Varnodes in the Decompiler Varnodes are the central variable concept for the decompiler. @@ -992,7 +992,7 @@ - + HighVariable A HighVariable is a set varnodes that, taken @@ -1027,7 +1027,7 @@ Merging 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 - ) provides the fundamental restriction on this process. + ) 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 can be merged. @@ -1045,11 +1045,11 @@ prioritizes variable pairs that are read and written within the same instruction and then pairs that are "near" each other in the control-flow of the function. To a limited extent, users are able to control this kind of merging - (See ). + (See ). - + Prototype Model Functions in high-level languages manipulate symbols like parameters and return values that @@ -1083,7 +1083,7 @@ If the parameter is stored on the stack, the storage location is viewed as a constant offset in the stack space, where the offset is relative to the incoming value of stack pointer - (See the discussion in ). + (See the discussion in ). The return value for the function, similarly, is stored at a single memory location. It @@ -1117,7 +1117,7 @@ - + Program Annotations Affecting the Decompiler
@@ -1126,7 +1126,7 @@ Individual machine instructions 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 ), + processor specific form into Ghidra's IR language (see ), which provides both the control-flow behavior of the instruction and the detailed semantics describing how the processor and memory state is affected. The translation is controlled by the underlying processor model and cannot be directly altered from the tool. Users @@ -1357,7 +1357,7 @@ - + Warning Comments The decompiler can generate internal warnings during its analysis and will incorporate @@ -1442,16 +1442,16 @@ - + - + - + - + @@ -1677,7 +1677,7 @@ Structured data-types are fully supported. The decompiler does not automatically infer structures when analyzing a function; it propagates structured data-types 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 . + structures can be triggered by the user, see . @@ -1860,7 +1860,7 @@ of a particular function in the Program. Formally, a stack address is defined as an offset relative to the incoming value of the stack pointer and exists in the stack address space associated with the function. See the discussion - in . A stack annotation then is a variable annotation + in . A stack annotation 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 local to that function. @@ -1903,7 +1903,7 @@ There may be more than one annotation, for different variables, that share the same register storage location. An annotation is associated with a first use point that describes where - the register first holds a value for the particular variable. (See the discussion - ) + the register first holds a value for the particular variable. (See the discussion - ) 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 merging process, but the full extent is not stored in the annotation. @@ -1915,7 +1915,7 @@ Variable annotations can have a temporary register 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 unique - space in . These registers do not have a meaningful name, and + space in . These registers do not have a meaningful name, and the specific storage address may change on successive decompilations. So within the Listing window, this annotation is displayed as part of the function header, with syntax like: @@ -1972,7 +1972,7 @@ The calling convention used by the function can be specified as part of the function prototype. The convention - is specified by name, referring to the formal that describes how storage + is specified by name, referring to the formal that describes how storage locations are selected for individual parameters along with other information about how the compiler treats the function. @@ -1983,7 +1983,7 @@ The name "unknown" is reserved to indicate that nothing is known about the calling convention. If set to "unknown", depending on context, the decompiler may assign the calling convention based on - the Prototype Evaluation option (See ), or it + the Prototype Evaluation option (See ), or it may use the default calling convention for the architecture. @@ -2207,9 +2207,38 @@
+
+ Register Values + + A register value 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 Register Values), + 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. + + + A register value is set by highlighting the region of code in the Listing Window and then invoking the + Set Register Values ... command + from the pop-up menu. The beginning and end of a region is indicated in the Listing Window with + assume directives, and regions can be generally viewed from the + Register Manager window. + + + 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 not + affected at all. + +
+ - + Decompiler Options @@ -2393,7 +2422,7 @@ Users can actively set whether specific memory regions are considered read-only through the Memory Manager, and individual data elements can be marked as constant via the Mutability setting - (See ). + (See ). @@ -2496,7 +2525,7 @@ Assign the background color used to highlight characters matching the current Find pattern. - See . + See . @@ -2529,7 +2558,7 @@ - + Display <kind-of> Comments @@ -2616,7 +2645,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 - indicate unusual conditions or possible errors (See ). + indicate unusual conditions or possible errors (See ). @@ -2696,7 +2725,7 @@ 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 . + decompiler analysis. See the discussion in . @@ -2714,14 +2743,14 @@ - + 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 . + discussion in . @@ -2794,7 +2823,7 @@ one or more warnings during the process. These warnings are integrated into the output as source code comments starting with label WARNING:. 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 ) + associated with the warning. (See )
@@ -2961,6 +2990,17 @@ + + Graph AST Control Flow + + 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. + + +
@@ -3091,7 +3131,7 @@ variable or operation affected. - + Auto Create Structure Automatically create a structure data-type for a selected variable @@ -3110,7 +3150,7 @@ 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 structure definition. - (See ) + (See ) @@ -3171,24 +3211,47 @@ - + + Commit Local Names> + + 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. + + + Parameters are not affected by this command, see . + 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 variable can be performed directly on the corresponding annotations in the Listing Window, + using various methods (See ). + Data-types are not forced for new annotations, they are created with + an undefined data-type, which allows the decompiler to refine + its view of the variable's data-type as new information becomes available + (See ). + + + + Commit Params/Return Commit the decompiler's analysis of the input parameters and return value of the current - function to the Program database. + function as annotations to the Program database. In the absence of either imported or user defined 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, effectively synching the disassembly's and - decompiler's view of the function prototype. + displayed in the window, creating a matching Variable Annotation for each input + parameter and the return value. The new annotations will be displayed in the + Listing Window as part of the function header, and the action effectively + synchronizes the disassembly view and decompiler's view of the function prototype. Committed prototype information is used both when decompiling the function itself and when decompiling other functions that call it. - The committed information is forcing on the decompiler, and it will + The committed annotations are forcing on the decompiler, 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 undefined @@ -3270,6 +3333,20 @@ + + Find ... + + Search for strings within the active window, in the current decompiler output. + + + The command brings up a dialog where a search pattern can 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 Next button is hit, or backward for the + Previous button. Any match is highlighted in the window, + and the cursor is set to the start of the match. + + + Highlight @@ -3391,6 +3468,96 @@ + + Override Signature + + Override the function prototype corresponding to the sub-function under the cursor. + + + This action can be triggered at call sites, where the function + being decompiled is calling into another sub-function. Users must select either the token representing + the sub-function's name or the tokens representing the function pointer at the call site. + A dialog is brought up where the a complete function declaration, specifying + the return data-type along with the name and data-type for each input parameter. Additionally, + the "Calling Convention", "In Line", and "No Return" properties of the function prototype + can be set (See ). + + + Confirming the dialog forces the new function prototype on the decompiler's view of the sub-function, + but only for the single selected call site. + + + 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 + command for instance. In this situation, the "Override Signature" + command is still possible, but it will bring up a confirmation dialog. + + + + + Reference ... + + Find Uses of <data-type> + + Calculate locations in the Program that reference the data-type + of the token under the cursor. Results are collected in a + Location References Dialog, + which displays a row for each reference with its address and other context. + + + Uses (references) specifically are to variables that have been assigned the data-type. + References to parameters and global variables are always listed. + If the Dynamic Data Type Discovery option is on + (see To Find Location References to Data Types), + the decompiler's propagation analysis is invoked on all functions to discover local + variables as well. + + + + Find References to <function> + + Display locations in the Program that reference the function + associated with the token under the cursor. Results are collected in a + Location References Dialog, + which displays a row for each reference with its address and other context. + + + References include both instructions and data referring to the entry point + address of the function. + + + + Show References to Address + + Display locations in the Program that reference the address + associated with the token under the cursor. Results are collected in a + Location References Dialog, + which displays a row for each reference with its address and other context. + + + The selected address is of the instruction most closely associated with the + variable or operator represented by the token. + + + + + + Remove Signature Override + + Remove the overriding function prototype applied previously to the sub-function under the cursor. + + + This action can only be triggered at call sites, where an overriding + prototype was previously placed by the command. As with + this command, users must select either the token representing the sub-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. + + + Rename Function @@ -3429,7 +3596,12 @@ The action brings up a dialog prepopulated with the current name of the field. Editing and confirming this dialog immediately changes - the corresponding data-type definition. The dialog enforces unique field names. + field's name in its corresponding structure definition. The dialog enforces unique field names. + + + If the initial name looks like field_0x.., 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 "undefined". The change to the definition is visible globally @@ -3439,8 +3611,8 @@ Within a decompiler window, field name tokens are presented in context, showing how they are used within the code flow of the current function. - Combined with and - , this action allows a + Combined with and + , this action allows a structure to be created and filled in based on this context. @@ -3472,7 +3644,7 @@ - + Rename Variable Rename the local variable or parameter currently under the cursor. @@ -3504,7 +3676,7 @@ - + Retype Field Change the data-type of the field currently under the cursor within its @@ -3520,7 +3692,7 @@ The change to the definition is visible globally throughout the Program, - anywhere the data-type is referenced,and is forcing + anywhere the data-type is referenced, and is forcing on the decompiler (see ). 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. @@ -3547,7 +3719,28 @@ - + + Retype Return + + Change the data-type of the current function's return value. + + + 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 <RETURN>) did not exist previously, one is created. + + + As input parameter annotations and the return value annotation must be commited 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 + , and a confirmation dialog comes up to notify the user. + + + + Retype Variable Change the data-type of the local variable or parameter currently under the cursor. @@ -3580,6 +3773,27 @@ + + Split Out As New Variable + + Split a high-level variable so that the selected token becomes a new variable with the smallest + possible range. + + + The decompiler defines high-level variables in terms of varnodes 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 . + + + 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. + + +