The StructureRecovery plugin allows users to build a structure in a target program based on the field uses in a source program. The process involves three steps. First, a source program is mined for field references from a known version of the structure to recover the use addresses and offsets. Second, functions in the source program bookmarked by field use are matched to functions in the target program using the local variation of BSim, which does not require a database. Third, BSim is used to create 'pinnings' between the data-flow graphs for each pair of functions which identify vertex-vertex correspondences using the decoompiler's diffing algorithm. Vertices with addresses from the first step are examined to identify offset information, which then becomes input to the construction of a new structure in the target program.
The success of this process depends on a number of factors. There are cases, for instance, in which nested structures may be missed by the structure use task, and, of course, certain fields may not be referenced at all. BSim, here as elsewhere, depends on a number of parameters that determine what constitutes a match, which are exposed as options. Unmatched functions will potentially result in gaps in the structure. Finally, the pinning comparison attempts to reconcile disparate pcode representations, but may fail in more complicated scenarios. When successful, the resulting structure will be stored in the target program's DataTypeManager as "RECOVERED_structure_name".
Each of the three tasks is relatively expensive. It may be necessary to save results from each across sessions. This is done using bookmarks (viewable from the listing or the Bookmarks viewer), which capture the structure use and function-to-function matches. The former are represented as "USES_structure_name_offset:address"; the latter as "source function id→target function id". The function-match bookmarks will be present in both the source and target programs.
ALL tasks should run with the source program active.
Uses BSim to match functions with structure use in the source program to similar functions in a target program.
Converts (persistent) bookmarks containing structure-use information, typically generated by the 'Tag Structure Use' action, to a (non-persistent) map and vice-versa.
Converts (persistent) bookmarks containing function-function matches, typically generated by the 'Match Functions' action, to a (non-persistent) map and vice-versa.
Options governing various aspects of the structure recovery.
The full path to the data type to be replicated ('Tag Structure Use' will query if empty).
Should bookmarks by generated by 'Tag Structure Use'.
The largest offset considered valid by 'Generate structure' (prevents confusion between offsets and addresses).
Comma-separated hex values to be ignored by 'Generate structure'. Principally used when analyzing a randomized structure that amalgamates randomized fields in a common block, e.g. 0x40 for the Linux task_struct randomized with symbols.