merge.hpp File Reference

Merge functionality. More...

Go to the source code of this file.

Classes
class	merge_data_t
	class to contain public info about the merge process More...
struct	merge_data_t::item_block_locator_t
	several items can be grouped into a block. More...
struct	merge_handler_params_t
	Merge handler parameters. More...
struct	moddata_diff_helper_t
	helper class for module data diff source More...
struct	merge_node_helper_t
	abstract adapter to provide access to non-standard netnode array entries More...
struct	merge_node_info_t
	field descriptor used to organize merging of a netnode array More...
struct	merge_node_info2_t

Typedefs
using	merge_handlers_t = qvector<merge_handler_t *>
typedef merge_node_helper_t *	merge_node_helper_creator_t(merge_data_t &md, int dbctx_id)
using	merge_node_hlpfunc_creator_t = std::function<merge_node_helper_creator_t>

Enumerations
enum	nds_flags_t {   NDS_IS_BOOL = 0x0001 , NDS_IS_EA = 0x0002 , NDS_IS_RELATIVE = 0x0004 , NDS_IS_STR = 0x0008 ,   NDS_SUPVAL = 0x0010 , NDS_BLOB = 0x0020 , NDS_EV_RANGE = 0x0040 , NDS_EV_FUNC = 0x0080 ,   NDS_MAP_IDX = 0x0100 , NDS_MAP_VAL = 0x0200 , NDS_VAL8 = 0x1000 , NDS_INC = 0x2000 ,   NDS_UI_ND = 0x4000 }
	netnode value modificators (to be used in nodeval_diff_source, see below) More...

Functions
enum merge_kind_t	ENUM_SIZE (uint32)
	Kinds of merge handlers.
idaman bool ida_export	is_diff_merge_mode ()
	Return TRUE if IDA is running in diff mode (MERGE_POLICY_MDIFF/MERGE_POLICY_VDIFF)
	DECLARE_TYPE_AS_MOVABLE (merge_node_info_t)
	DECLARE_TYPE_AS_MOVABLE (merge_node_info2_t)
idaman merge_handler_t *ida_export	create_nodeval_merge_handler (const merge_handler_params_t &mhp, const char *label, int moddata_id, const char *nodename, uchar tag, uint32 nds_flags, merge_node_hlpfunc_creator_t nhc=nullptr, bool skip_empty_nodes=true)
	Create a merge handler for netnode scalar/string values.
idaman merge_handler_t *ida_export	create_nodeval_merge_handler2 (const merge_handler_params_t &mhp, const char *label, int moddata_id, const char *nodename, uchar tag, uint32 nds_flags, merge_node_helper_t *node_helper=nullptr, bool skip_empty_nodes=true)
idaman void ida_export	create_nodeval_merge_handlers (merge_handlers_t *out, const merge_handler_params_t &mhp, int moddata_id, const char *nodename, const merge_node_info_t *valdesc, size_t nvals, bool skip_empty_nodes=true)
	Create a serie of merge handlers for netnode scalar/string values (call create_nodeval_merge_handler() for each member of VALDESC)
idaman void ida_export	create_nodeval_merge_handlers2 (merge_handlers_t *out, const merge_handler_params_t &mhp, int moddata_id, const char *nodename, const merge_node_info2_t *valdesc, size_t nvals, bool skip_empty_nodes=true)
idaman void ida_export	destroy_moddata_merge_handlers (int data_id)
idaman ssize_t ida_export	get_ea_diffpos_name (qstring *out, ea_t ea)
	Get nice name for EA diffpos.

Detailed Description

Merge functionality.

 NOTE: this functionality is available in IDA Teams (not IDA Pro)

 There are 3 databases involved in merging: base_idb, local_db, and remote_idb.
  - base_idb: the common base ancestor of 'local_db' and 'remote_db'.
           in the UI this database is located in the middle.
  - local_idb: local database that will contain the result of the merging.
           in the UI this database is located on the left.
  - remote_idb: remote database that will merge into local_idb. It may reside
           locally on the current computer, despite its name.
           in the UI this database is located on the right.
 base_idb and remote_idb are opened for reading only.
 base_idb may be absent, in this case a 2-way merging is performed.

 Conflicts can be resolved automatically or interactively.
 The automatic resolving scores the conflicting blocks and takes the better one.
 The interactive resolving displays the full rendered contents side by
 side, and expects the user to select the better side for each conflict.

 Since IDB files contain various kinds of information, there are many
 merging phases. The entire list can be found in merge.cpp. Below are
 just some selected examples:
   - merge global database settings (inf and other global vars)
   - merge segmentation and changes to the database bytes
   - merge various lists: exports, imports, loaded tils, etc
   - merge names, functions, function frames
   - merge debugger settings, breakpoints
   - merge struct/enum views
   - merge local type libraries
   - merge the disassembly items (i.e. the segment contents)
     this includes operand types, code/data separation, etc
   - merge plugin specific info like decompiler types, dwarf mappings, etc

 To unify UI elements of each merge phase, we use merger views:
   - A view that consists of 2 or 3 panes: left (local_idb) and right (remote_idb).
     The common base is in the middle, if present.
   - Rendering of the panes depends on the phase, different phases
     show different contents.
   - The conflicts are highlighted by a colored background. Also,
     the detail pane can be consulted for additional info.
   - The user can select a conflict (or a bunch of conflicts) and say
     "use this block".
   - The user can browse the panes as he wishes. He will not be forced
     to handle conflicts in any particular order. However, once he
     finishes working with a merge handler and proceeds to the next one,
     he cannot go back.
   - Scrolling the left pane will synchronously scroll the right pane
     and vice versa.
   - There are the navigation commands like "go to the prev/next conflict"
   - The number of remaining conflicts to resolve is printed in the
     "Progress" chooser.
   - The user may manually modify local database inside the merger view.
     For that he may use the regular hotkeys. However, editing the database
     may lead to new conflicts, so we better restrict the available actions
     to some reasonable minimum. Currently, this is not implemented.

 IDA works in a new "merge" mode during merging. In this mode most
 events are not generated. We forbid them to reduce the risk that a rogue
 third-party plugin that is not aware of the "merge" mode would spoil something.

 For example, normally renaming a function causes a cascade of events
 and may lead to other database modifications. Some of them may be
 desired, some - not. Since there are some undesired events, it is
 better to stop generating them. However, some events are required to
 render the disassembly listing. For example, ev_ana_insn, av_out_insn.
 This is why some events are still generated in the "merge" mode.

 To let processor modules and plugins merge their data, we introduce
 a new event: ev_create_merge_handlers. It is generated immediately after
 opening all three idbs. The interested modules should react to this
 event by creating new merge handlers, if they need them.

 While the kernel can create arbitrary merge handlers, modules
 can create only the standard ones returned by:

   create_nodeval_merge_handler()
   create_nodeval_merge_handlers()
   create_std_modmerge_handlers()

 We do not document merge_handler_t because once a merge handler is
 created, it is used exclusively by the kernel.

 See mergemod.hpp for more information about the merge mode for modules.

Typedef Documentation

merge_handlers_t

using merge_handlers_t = qvector<merge_handler_t *>

merge_node_helper_creator_t

typedef merge_node_helper_t * merge_node_helper_creator_t(merge_data_t &md, int dbctx_id)

merge_node_hlpfunc_creator_t

using merge_node_hlpfunc_creator_t = std::function<merge_node_helper_creator_t>

Enumeration Type Documentation

nds_flags_t

enum nds_flags_t

netnode value modificators (to be used in nodeval_diff_source, see below)

Enumerator
NDS_IS_BOOL	boolean value
NDS_IS_EA	EA value.
NDS_IS_RELATIVE	value is relative to index (stored as delta)
NDS_IS_STR	string value
NDS_SUPVAL	stored as netnode supvals (not scalar)
NDS_BLOB	stored as netnode blobs
NDS_EV_RANGE	enable default handling of mev_modified_ranges, mev_deleting_segm
NDS_EV_FUNC	enable default handling of mev_added_func/mev_deleting_func
NDS_MAP_IDX	apply ea2node() to index (==NETMAP_IDX)
NDS_MAP_VAL	apply ea2node() to value. Along with NDS_INC it gives effect of NETMAP_VAL, examples: altval_ea : NDS_MAP_IDX charval : NDS_VAL8 charval_ea: NDS_MAP_IDX|NDS_VAL8 eaget : NDS_MAP_IDX|NDS_MAP_VAL|NDS_INC
NDS_VAL8	use 8-bit values (==NETMAP_V8)
NDS_INC	stored value is incremented (scalars only)
NDS_UI_ND	UI: no need to show diffpos detail pane, MH_UI_NODETAILS, make sense if merge_node_helper_t is used.

Function Documentation

ENUM_SIZE()

enum merge_kind_t ENUM_SIZE

(

uint32

)

Kinds of merge handlers.

< netnode (no merging, to be used in idbunits)

< auto queues

< merge the inf variable (global settings)

< merge encodings

< merge default encodings

< merge scripts common info

< merge scripts

< merge custom data type and formats

< merge custom calling conventions

< merge enums

< merge structs (globally: add/delete structs entirely)

< merge type libraries

< merge tinfo

< merge struct members

< merge UDT members (local types)

< merge ghost structure comment

< merge member comments for ghost struc

< merge selectors

< merge flag storage types

< merge segments

< merge segment groups

< merge segment registers

< merge orphan bytes

< merge byte values

< merge fixups

< merge manual memory mapping

< merge exports

< merge imports

< merge patched bytes

< merge flags64_t

< merge extra next or prev lines

< merge aflags for mapped EA

< IM ("$ ignore micro") flags

< merge fileregions

< merge hidden ranges

< merge source files ranges

< merge func info

< merge frames (globally: add/delete frames entirely)

< merge function frame info (frame members)

< merge SP change points

< merge flows

< merge crefs

< merge drefs

< merge breakpoints

< merge watchpoints

< merge bookmarks

< merge try blocks

< merge std dirtrees

< merge vftables

< signatures

< problems

< UI

< dekstops

< notepad

< loader data

< debugger data

< manual memory regions (debugger)

< lumina function metadata

< last predefined merge handler type. please note that there can be more merge handler types, registered by plugins and processor modules.

< insert to the end of handler list, valid for merge_handler_params_t::insert_after

is_diff_merge_mode()

idaman bool ida_export is_diff_merge_mode

(

)

Return TRUE if IDA is running in diff mode (MERGE_POLICY_MDIFF/MERGE_POLICY_VDIFF)

DECLARE_TYPE_AS_MOVABLE() [1/2]

DECLARE_TYPE_AS_MOVABLE

(

merge_node_info_t

)

DECLARE_TYPE_AS_MOVABLE() [2/2]

DECLARE_TYPE_AS_MOVABLE

(

merge_node_info2_t

)

create_nodeval_merge_handler()

idaman merge_handler_t *ida_export create_nodeval_merge_handler	(	const merge_handler_params_t &	mhp,
		const char *	label,
		int	moddata_id,
		const char *	nodename,
		uchar	tag,
		uint32	nds_flags,
		merge_node_hlpfunc_creator_t	nhc = nullptr,
		bool	skip_empty_nodes = true )

Create a merge handler for netnode scalar/string values.

Parameters

mhp	merging parameters
label	handler short name (to be be appended to mhp.label)
moddata_id	module data ID (to be passed to get_module_data)
nodename	netnode name
tag	a tag used to access values in the netnode
nds_flags	netnode value attributes (a combination of nds_flags_t)
nhc	a factory to create instances of merge_node_helper_t
skip_empty_nodes	do not create handler in case of empty netnode

Returns

diff source object (normally should be attahced to a merge handler)

create_nodeval_merge_handler2()

idaman merge_handler_t *ida_export create_nodeval_merge_handler2	(	const merge_handler_params_t &	mhp,
		const char *	label,
		int	moddata_id,
		const char *	nodename,
		uchar	tag,
		uint32	nds_flags,
		merge_node_helper_t *	node_helper = nullptr,
		bool	skip_empty_nodes = true )

create_nodeval_merge_handlers()

idaman void ida_export create_nodeval_merge_handlers	(	merge_handlers_t *	out,
		const merge_handler_params_t &	mhp,
		int	moddata_id,
		const char *	nodename,
		const merge_node_info_t *	valdesc,
		size_t	nvals,
		bool	skip_empty_nodes = true )

Create a serie of merge handlers for netnode scalar/string values (call create_nodeval_merge_handler() for each member of VALDESC)

Parameters

out	[out] created handlers will be placed here
mhp	merging parameters
moddata_id	module data ID (to be passed to get_module_data)
nodename	netnode name
valdesc	array of handler descriptions
nvals	number of members in VALDESC
skip_empty_nodes	do not create handlers for empty netnodes

Returns

diff source object (normally should be attahced to a merge handler)

create_nodeval_merge_handlers2()

idaman void ida_export create_nodeval_merge_handlers2	(	merge_handlers_t *	out,
		const merge_handler_params_t &	mhp,
		int	moddata_id,
		const char *	nodename,
		const merge_node_info2_t *	valdesc,
		size_t	nvals,
		bool	skip_empty_nodes = true )

destroy_moddata_merge_handlers()

idaman void ida_export destroy_moddata_merge_handlers

(

int

data_id

)

get_ea_diffpos_name()

idaman ssize_t ida_export get_ea_diffpos_name	(	qstring *	out,
		ea_t	ea )

Get nice name for EA diffpos.

Parameters

	ea	diffpos
[out]	out	nice name

Note

See also

get_nice_colored_name