# Interface: com.pnfsoftware.jeb.core.units.code.IDFA Specification of a data flow analysis objects for control flow graphs. ## Static Field: STANDARD_COLLECTION_FLAGS Type: `int` Constant value: `3` Description: Standard setting for variable collection flags: conservative. ## Static Field: STANDARD_INTEGRATE_INPUTS Type: `boolean` Constant value: `true` Description: Standard setting for routine inputs integration into output maps and reaching\-register chains: enabled. ## Method: checkNoUse - parameter: `insnAddress`, type: `long` - parameter: `varId`, type: `int` - parameter: `reachOutIsUse`, type: `boolean` - parameter: `maxBlocks`, type: `int` - return type: `int` Description: Check whether a variable, defined at the provided instruction, is not used. parameter: insnAddress: initial instruction address parameter: varId: defined variable at the initial instruction parameter: reachOutIsUse: true if reaching out is considered a use parameter: maxBlocks: optional maximum block count return: 1: some uses; 0: no use; \-1: no use, but may be a meaningful output; \-2: unknown \(may be returned only if maxBlocks is positive\); \-3: error ## Method: checkNoUse - parameter: `insnAddress`, type: `long` - parameter: `varId`, type: `int` - parameter: `reachOutIsUse`, type: `boolean` - return type: `boolean` Description: Check whether a variable, defined at the provided instruction, is not used. parameter: insnAddress: initial instruction address parameter: varId: defined variable at the initial instruction parameter: reachOutIsUse: true if reaching out is considered a use return: true if the variable is not used, and optionally \(if reachOutIsUse is true\), is overwritten before reaching possible end\-blocks ## Method: checkNoUse - parameter: `insnAddress`, type: `long` - parameter: `varId`, type: `int` - return type: `boolean` Description: Check whether a variable, defined at the provided instruction, is not used. parameter: insnAddress: initial instruction address parameter: varId: defined variable at the initial instruction return: true if the variable is not used; reaching\-out is not considered a use ## Method: checkSingleDef - parameter: `addr`, type: `long` - parameter: `varid`, type: `int` - return type: `java.lang.Long` Description: Check whether a used variable has a single definition point. The def point may be explicit \(e.g. resulting from an assignment\) or implicit \(e.g. provided as a parameter to the routine, which is always represented as the address \-1\). parameter: addr: initial instruction address parameter: varid: used variable at the initial instruction \(it must be used at the provided address; else, refer to `checkSingleSource`\) return: single definition address, or null ## Method: checkSingleDef - parameter: `addr`, type: `long` - parameter: `varid`, type: `int` - parameter: `expectedDefAddress`, type: `long` - return type: `boolean` Description: Check whether a used variable has a specific single definition point. parameter: addr: instruction address parameter: varid: variable id parameter: expectedDefAddress: expected definition address return: true if the single definition is the expected address ## Method: checkSingleDefNoInput - parameter: `addr`, type: `long` - parameter: `varid`, type: `int` - return type: `java.lang.Long` Description: Check whether a used variable has a single explicit definition point. The def point cannot be a routine input \(i.e. the definition must be explicit\). parameter: addr: initial instruction address parameter: varid: used variable at the initial instruction return: single definition address, or null ## Method: checkSingleSource - parameter: `addr`, type: `long` - parameter: `varid`, type: `int` - parameter: `liveInIsDef`, type: `boolean` - return type: `java.lang.Long` Description: Check whether a variable has a single source. parameter: addr: instruction address parameter: varid: variable id parameter: liveInIsDef: true if live\-in variables are treated as definitions return: single source address, or null ## Method: checkSingleSource - parameter: `addr`, type: `long` - parameter: `varid`, type: `int` - return type: `java.lang.Long` Description: Check whether a variable has a single source. parameter: addr: instruction address parameter: varid: variable id return: single source address, or null ## Method: checkSingleSource - parameter: `addr`, type: `long` - parameter: `varid`, type: `int` - parameter: `expectedSourceAddress`, type: `long` - return type: `boolean` Description: Check whether a variable has a specific single source. parameter: addr: instruction address parameter: varid: variable id parameter: expectedSourceAddress: expected source address return: true if the single source is the expected address ## Method: checkSingleUse - parameter: `addr`, type: `long` - parameter: `varid`, type: `int` - return type: `java.lang.Long` Description: Check whether a defined variable has a single use. parameter: addr: instruction address parameter: varid: variable id return: single use address, or null ## Method: checkSingleUse - parameter: `addr`, type: `long` - parameter: `varid`, type: `int` - parameter: `expectedUseAddress`, type: `long` - return type: `boolean` Description: Check whether a defined variable has a specific single use. parameter: addr: instruction address parameter: varid: variable id parameter: expectedUseAddress: expected use address return: true if the single use is the expected address ## Method: collectInstructionAllDefs - parameter: `addr`, type: `long` - parameter: `r`, type: `java.util.Collection` Description: Collect all variables defined by an instruction. parameter: addr: instruction address parameter: r: output collection ## Method: collectInstructionAllUses - parameter: `addr`, type: `long` - parameter: `r`, type: `java.util.Collection` Description: Collect all variables used by an instruction. parameter: addr: instruction address parameter: r: output collection ## Method: getBlockDefUses - parameter: `addr`, type: `long` - parameter: `varid`, type: `int` - return type: `java.util.Collection` Description: Get block\-local use locations for a variable definition. parameter: addr: instruction address parameter: varid: variable id return: use locations ## Method: getBlockDefUses - parameter: `addr`, type: `long` - parameter: `varid`, type: `int` - parameter: `stopCount`, type: `int` - return type: `java.util.Collection` Description: Get block\-local use locations for a variable definition. parameter: addr: instruction address parameter: varid: variable id parameter: stopCount: optional stop count return: use locations ## Method: getBlockUseDefs - parameter: `addr`, type: `long` - parameter: `varid`, type: `int` - return type: `java.util.Collection` Description: Get block\-local definition locations for a variable use. parameter: addr: instruction address parameter: varid: variable id return: definition locations ## Method: getCfg - return type: `com.pnfsoftware.jeb.core.units.code.IControlFlowGraph>` Description: Retrieve a reference to the CFG object that will be accessed and modified when performing an analysis. return: control flow graph ## Method: getDUI - parameter: `addr`, type: `long` - return type: `com.pnfsoftware.jeb.core.units.code.DUI` Description: Get def\-use information for an instruction. parameter: addr: instruction address return: def\-use information ## Method: getDUI - parameter: `a`, type: `com.pnfsoftware.jeb.core.units.code.AddressableInstruction` - return type: `com.pnfsoftware.jeb.core.units.code.DUI` Description: Get def\-use information for an addressable instruction. parameter: a: addressable instruction return: def\-use information ## Method: getDUI - parameter: `addr`, type: `long` - parameter: `insn`, type: `InsnType` - return type: `com.pnfsoftware.jeb.core.units.code.DUI` Description: Get def\-use information for an instruction. parameter: addr: instruction address parameter: insn: instruction return: def\-use information ## Method: getDefUseChains - parameter: `addr`, type: `long` - return type: `java.util.Map>` Description: Get def\-use chains at an instruction. parameter: addr: instruction address return: def\-use chains ## Method: getDefUses - parameter: `addr`, type: `long` - parameter: `varid`, type: `int` - return type: `java.util.Collection` Description: Get use locations for a variable definition. parameter: addr: instruction address parameter: varid: a variable, which must be defined by the provided instruction return: a collection \(possibly empty\) or null if the variable is not defined by the instruction ## Method: getDefUses - parameter: `addr`, type: `long` - parameter: `varid`, type: `int` - parameter: `stopCount`, type: `int` - return type: `java.util.Collection` Description: Get use locations for a variable definition. parameter: addr: instruction address parameter: varid: a variable, which must be defined by the provided instruction parameter: stopCount: optional stop count \(\-1 to collect as many uses as possible\) return: a collection \(possibly empty\) or null if the variable is not defined by the instruction ## Method: getDefUses - parameter: `addr`, type: `long` - parameter: `varid`, type: `int` - parameter: `stopCount`, type: `int` - parameter: `recordReachOut`, type: `boolean` - return type: `java.util.Collection` Description: Get use locations for a variable definition. parameter: addr: instruction address parameter: varid: a variable, which must be defined by the provided instruction parameter: stopCount: optional stop count \(\-1 to collect as many uses as possible\) parameter: recordReachOut: if true, a variable reaching is considered used \(if so, the output list will contain \-1\) return: a collection \(possibly empty\) or null if the variable is not defined by the instruction ## Method: getInputMap - return type: `java.util.Map>` Description: Get the input map. return: input map ## Method: getInputMap - parameter: `varid`, type: `int` - return type: `java.util.Collection` Description: Get input locations for a variable. parameter: varid: variable id return: input locations ## Method: getInputs - return type: `java.util.Collection` Description: Get input variables. return: input variables ## Method: getInstructionAllDefs - parameter: `addr`, type: `long` - return type: `java.util.Collection` Description: Get all variables defined by an instruction. parameter: addr: instruction address return: defined variables ## Method: getInstructionAllUses - parameter: `addr`, type: `long` - return type: `java.util.Collection` Description: Get all variables used by an instruction. parameter: addr: instruction address return: used variables ## Method: getInstructionDefs - parameter: `addr`, type: `long` - return type: `java.util.Collection` Description: Get the variables defined by an instruction. parameter: addr: instruction address return: a list of variables defined by the instruction at index in the block ## Method: getInstructionPotentialDefs - parameter: `addr`, type: `long` - return type: `java.util.Collection` Description: Get variables potentially defined by an instruction. parameter: addr: instruction address return: a list of variables potentially defined by the instruction at index in the block; note that this data may not be present \(empty lists\) depending on DFA settings ## Method: getInstructionPotentialUses - parameter: `addr`, type: `long` - return type: `java.util.Collection` Description: Get variables potentially used by an instruction. parameter: addr: instruction address return: a list of variables potentially used by the instruction at index in the block; note that this data may not be present \(empty lists\) depending on DFA settings ## Method: getInstructionSpoiledDefs - parameter: `addr`, type: `long` - return type: `java.util.Collection` Description: Get variables potentially spoiled by an instruction. parameter: addr: instruction address return: a list of variables potentially spoiled by the instruction at index in the block; note that this data may not be present \(empty lists\) depending on DFA settings ## Method: getInstructionUses - parameter: `addr`, type: `long` - return type: `java.util.Collection` Description: Get the variables used by an instruction. parameter: addr: instruction address return: a list of variables used by the instruction at index in the block ## Method: getLiveChains - parameter: `b`, type: `com.pnfsoftware.jeb.core.units.code.IBasicBlock` - parameter: `idx`, type: `int` - parameter: `varid`, type: `int` - return type: `java.util.Collection` Description: Get live chains for a variable at a block location. parameter: b: basic block parameter: idx: instruction index parameter: varid: variable id return: live chains ## Method: getLiveChains - parameter: `b`, type: `com.pnfsoftware.jeb.core.units.code.IBasicBlock` - parameter: `idx`, type: `int` - parameter: `varid`, type: `int` - parameter: `stopcount`, type: `int` - return type: `java.util.Collection` Description: Get live chains for a variable at a block location. parameter: b: basic block parameter: idx: instruction index parameter: varid: variable id parameter: stopcount: optional stop count return: live chains ## Method: getLiveChains - parameter: `b`, type: `com.pnfsoftware.jeb.core.units.code.IBasicBlock` - parameter: `idx`, type: `int` - return type: `java.util.Map>` Description: Get live chains at a block location. parameter: b: basic block parameter: idx: instruction index return: live chains ## Method: getMaxBlocks - return type: `int` Description: Retrieve the maximum block count used for common DFA operations. See [#setMaxBlocks(int)](#setMaxBlocks(int)) for details. return: maximum block count ## Method: getOutputMap - parameter: `blk`, type: `com.pnfsoftware.jeb.core.units.code.IBasicBlock` - return type: `java.util.Map>` Description: Get the output map for a block. parameter: blk: basic block return: output map ## Method: getOutputMap - parameter: `blk`, type: `com.pnfsoftware.jeb.core.units.code.IBasicBlock` - parameter: `varid`, type: `int` - return type: `java.util.Collection` Description: Get output locations for a block and variable. parameter: blk: basic block parameter: varid: variable id return: output locations ## Method: getOutputMap - return type: `java.util.Map>` Description: Get the output map. return: output map ## Method: getOutputMap - parameter: `varid`, type: `int` - return type: `java.util.Collection` Description: Get output locations for a variable. parameter: varid: variable id return: output locations ## Method: getOutputs - parameter: `blk`, type: `com.pnfsoftware.jeb.core.units.code.IBasicBlock` - return type: `java.util.Collection` Description: Get output variables for a block. parameter: blk: basic block return: output variables ## Method: getOutputs - return type: `java.util.Collection` Description: Get output variables. return: output variables ## Method: getReachChains - parameter: `b`, type: `com.pnfsoftware.jeb.core.units.code.IBasicBlock` - parameter: `idx`, type: `int` - parameter: `varid`, type: `int` - return type: `java.util.Collection` Description: Get reach chains for a variable at a block location. parameter: b: basic block parameter: idx: instruction index parameter: varid: variable id return: reach chains ## Method: getReachChains - parameter: `b`, type: `com.pnfsoftware.jeb.core.units.code.IBasicBlock` - parameter: `idx`, type: `int` - parameter: `varid`, type: `int` - parameter: `stopcount`, type: `int` - return type: `java.util.Collection` Description: Get reach chains for a variable at a block location. parameter: b: basic block parameter: idx: instruction index parameter: varid: variable id parameter: stopcount: optional stop count return: reach chains ## Method: getReachChains - parameter: `b`, type: `com.pnfsoftware.jeb.core.units.code.IBasicBlock` - parameter: `idx`, type: `int` - return type: `java.util.Map>` Description: Get reach chains at a block location. parameter: b: basic block parameter: idx: instruction index return: reach chains ## Method: getUseDefChains - parameter: `addr`, type: `long` - return type: `java.util.Map>` Description: Get use\-def chains at an instruction. parameter: addr: instruction address return: use\-def chains ## Method: getUseDefs - parameter: `addr`, type: `long` - parameter: `varid`, type: `int` - return type: `java.util.Collection` Description: Get definition locations for a variable use. parameter: addr: instruction address parameter: varid: a variable, which must be used by the provided instruction return: a collection \(possibly empty\) or null if the variable is not used by the instruction ## Method: getUseDefs - parameter: `addr`, type: `long` - parameter: `varid`, type: `int` - parameter: `stopCount`, type: `int` - return type: `java.util.Collection` Description: Get definition locations for a variable use. parameter: addr: instruction address parameter: varid: a variable, which must be used by the provided instruction parameter: stopCount: optional stop count return: a collection \(possibly empty\) or null if the variable is not used by the instruction ## Method: getUseDiscrepancies - parameter: `addr`, type: `long` - return type: `java.util.Collection` Description: Retrieve the list of use\-discrepancies at the provided instruction address. parameter: addr: instruction address return: a list of variables whose usage at the provided location appears to be incorrect \(i.e. not all paths to this usage carry a definition if the variable\) ## Method: getVariableCollectionFlags - return type: `int` Description: Retrieve the variable collection flags. return: flags, see [DefUseInfo](DefUseInfo) ## Method: getVariableInformationProvider - return type: `com.pnfsoftware.jeb.core.units.code.ICFGOwnerContext` Description: Get the variable information provider. return: variable information provider ## Method: invalidate Description: Invalidate the analysis. Clients have the responsibility to invalidate an analysis if the CFG was modified in such a way that data flow should be recalculated. ## Method: invalidateForRemoval - parameter: `addr0`, type: `long` Description: Selectively invalidate the cache in preparation for an instruction pseudo\-removal \(neutering\). This method should be called before neutering takes place. parameter: addr0: address of the start instruction; it is assumed that this instruction is no\-throw ## Method: invalidateForSubstitution - parameter: `addr0`, type: `long` - parameter: `addr1coll`, type: `java.util.Collection` - parameter: `srccoll`, type: `java.util.Collection` Description: Selectively invalidate the cache in preparation for an expression\-substitution. This method should be called before the substitution by an immediate took place. parameter: addr0: address of the start instruction, which defines the variable being substituted; it is assumed that this instruction is no\-throw parameter: addr1coll: mandatory collection of addresses where the substitutions will take place place parameter: srccoll: optional collection of source instructions; if not provided, all instructions defining some of the substituted variables will be invalidated from the cache ## Method: invalidatePostSimpleSubstitutionWithMultiDefs - parameter: `addr0coll`, type: `java.util.Collection` - parameter: `addr1`, type: `long` - parameter: `varid`, type: `int` Description: Selectively invalidate DFA cache after the substitution of a variable `X` by an immediate. This method should be called after the substitution by an immediate took place. parameter: addr0coll: collection of equivalent source instructions defining a target var `X` \(e.g. X=3\); these instructions must be left as\-is when calling this method; it is assumed that these instructions are no\-throw parameter: addr1: destination instruction, whose target variable `X` was replaced by a constant parameter: varid: the variable that was propagated \(`X`\) ## Method: isAlive - parameter: `b`, type: `com.pnfsoftware.jeb.core.units.code.IBasicBlock` - parameter: `idx`, type: `int` - parameter: `varid`, type: `int` - return type: `boolean` Description: Determine whether a variable is alive at a block location. parameter: b: basic block parameter: idx: instruction index parameter: varid: variable id return: true if the variable is alive ## Method: isAlwaysExamineIrregularFlows - return type: `boolean` Description: Determine whether irregular flows are always examined. return: true if irregular flows are always examined ## Method: isConservative - return type: `boolean` Description: Convenience method used to determine whether the variable collection flags are [DefUseInfo#CONSERVATIVE](DefUseInfo#CONSERVATIVE). return: true if conservative collection is enabled ## Method: isIntegrateCalculatedInputRegisters - return type: `boolean` Description: Determine whether calculated input registers are integrated. return: true if calculated input registers are integrated ## Method: isReaching - parameter: `b`, type: `com.pnfsoftware.jeb.core.units.code.IBasicBlock` - parameter: `idx`, type: `int` - parameter: `varid`, type: `int` - return type: `boolean` Description: Determine whether a variable reaches a block location. parameter: b: basic block parameter: idx: instruction index parameter: varid: variable id return: true if the variable is reaching ## Method: isTerminator - parameter: `blk`, type: `com.pnfsoftware.jeb.core.units.code.IBasicBlock` - return type: `boolean` Description: Determine whether the provided block is a terminator. A terminator has no output and its final instruction is a clean routine terminator. parameter: blk: block to test return: true if the block is a clean terminator ## Method: isUseDiscrepancy - parameter: `addr`, type: `long` - parameter: `varid`, type: `int` - return type: `boolean` Description: Determine whether a use discrepancy exists for a variable. parameter: addr: instruction address parameter: varid: variable id return: true if a use discrepancy exists ## Method: isValid - return type: `boolean` Description: Determine whether the current analysis was performed and is valid. return: true if the analysis is valid ## Method: isVarReachingFromTo - parameter: `varid`, type: `int` - parameter: `addr0`, type: `long` - parameter: `addr1`, type: `long` - return type: `java.lang.Boolean` Description: Determine if a variable used by the start instruction reaches the final instruction with the same value. Important notes: \- This method provides a *must\-reach* result: if a multiple paths exist from source to sink, where the variable reaches the sink via some paths, but not on others \(it is overwritten\), the method returns false. \- This method works from the source to the sink, and provides the guarantee that the variable was not overwritten when it reached the sink. There is no guarantee provided at the sink itself regarding other paths that may exist from different sources to the same sink. \- This method also checks that the paths from the sink back that may connect back to the sink do not overwrite the variable defined at the source. parameter: varid: variable id parameter: addr0: source: start address, exclusive parameter: addr1: sink: final address, also exclusive return: success indicator; null means unknown ## Method: isVarReachingFromTo - parameter: `varid`, type: `int` - parameter: `b0`, type: `com.pnfsoftware.jeb.core.units.code.IBasicBlock` - parameter: `i0`, type: `int` - parameter: `b1`, type: `com.pnfsoftware.jeb.core.units.code.IBasicBlock` - parameter: `i1`, type: `int` - return type: `java.lang.Boolean` Description: Determine if a variable used by the start instruction reaches the final instruction with the same value. Important notes: \- This method provides a *must\-reach* result: if a multiple paths exist from source to sink, where the variable reaches the sink via some paths, but not on others \(it is overwritten\), the method returns false. \- This method works from the source to the sink, and provides the guarantee that the variable was not overwritten when it reached the sink. There is no guarantee provided at the sink itself regarding other paths that may exist from different sources to the same sink. \- This method also checks that the paths from the sink back that may connect back to the sink do not overwrite the variable defined at the source. parameter: varid: variable id parameter: b0: start block \(source\) parameter: i0: final block \(sink\) parameter: b1: index of the start instruction in the start block, exclusive parameter: i1: index of the final instruction in the final block, also exclusive return: success indicator; null means unknown ## Method: isVarReachingFromTo - parameter: `varid`, type: `int` - parameter: `b0`, type: `com.pnfsoftware.jeb.core.units.code.IBasicBlock` - parameter: `i0`, type: `int` - parameter: `b1`, type: `com.pnfsoftware.jeb.core.units.code.IBasicBlock` - parameter: `i1`, type: `int` - parameter: `performExtendedChecks`, type: `boolean` - parameter: `maxBlocks`, type: `int` - return type: `java.lang.Boolean` Description: Determine if a variable used by the start instruction reaches the final instruction with the same value. Important notes: \- This method provides a *must\-reach* result: if a multiple paths exist from source to sink, where the variable reaches the sink via some paths, but not on others \(it is overwritten\), the method returns false. \- This method works from the source to the sink, and provides the guarantee that the variable was not overwritten when it reached the sink. There is no guarantee provided at the sink itself regarding other paths that may exist from different sources to the same sink. \- if \`performExtendedChecks\` is true, this method also checks that the paths from the sink back that may connect back to the sink do not overwrite the variable defined at the source. parameter: varid: variable id parameter: b0: start block \(source\) parameter: i0: final block \(sink\) parameter: b1: index of the start instruction in the start block, exclusive parameter: i1: index of the final instruction in the final block, also exclusive parameter: performExtendedChecks: true to perform extended reachability checks parameter: maxBlocks: optional maximum count of blocks to be explored before failing return: success indicator; null means unknown ## Method: notifyInstructionUpdate - parameter: `addr`, type: `long` Description: Notify the DFA that an instruction was updated. parameter: addr: instruction address ## Method: perform Description: Perform data flow analysis on the CFG. Upon return, basic blocks will have their data chains \(ud and du, full and simple\) set up and accessible. ## Method: setAlwaysExamineIrregularFlows - parameter: `enabled`, type: `boolean` - return type: `boolean` Description: Set whether irregular flows should always be examined. parameter: enabled: true to always examine irregular flows return: the previous value for this setting ## Method: setConservative Description: Convenience method used to set or remove [DefUseInfo#CONSERVATIVE](DefUseInfo#CONSERVATIVE) variable collection flags. ## Method: setIntegrateCalculatedInputRegisters - parameter: `enabled`, type: `boolean` - return type: `boolean` Description: Set whether calculated input registers should be integrated. parameter: enabled: true to integrate calculated input registers return: the previous value for this setting ## Method: setMaxBlocks - parameter: `maxBlocks`, type: `int` - return type: `int` Description: Set an exploration threshold for most DFA operations. By default, there is no threshold. The threshold is a block count; if a block count is reached, a chain may contain a reference to the invalid address \-2 in order to indicate an incomplete result. parameter: maxBlocks: \-1 means no limit return: the previous value for this setting ## Method: setVariableCollectionFlags - parameter: `varCollectionFlags`, type: `int` Description: Set the variable collection flags. parameter: varCollectionFlags: flags, see [DefUseInfo](DefUseInfo) ## Method: setVariableInformationProvider - parameter: `provider`, type: `com.pnfsoftware.jeb.core.units.code.ICFGOwnerContext` - return type: `com.pnfsoftware.jeb.core.units.code.ICFGOwnerContext` Description: Set the variable information provider. parameter: provider: variable information provider return: the previously set provider