# 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: 
parameter: maxBlocks: 
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: 
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: 

## Method: checkSingleDef
- parameter: `addr`, type: `long`
- parameter: `varid`, type: `int`
- parameter: `expectedDefAddress`, type: `long`
- return type: `boolean`


## 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: 

## Method: checkSingleSource
- parameter: `addr`, type: `long`
- parameter: `varid`, type: `int`
- parameter: `liveInIsDef`, type: `boolean`
- return type: `java.lang.Long`

Description: 
parameter: addr: 
parameter: varid: 
parameter: liveInIsDef: 
return: 

## Method: checkSingleSource
- parameter: `addr`, type: `long`
- parameter: `varid`, type: `int`
- return type: `java.lang.Long`

Description: 
parameter: addr: 
parameter: varid: 
return: 

## Method: checkSingleSource
- parameter: `addr`, type: `long`
- parameter: `varid`, type: `int`
- parameter: `expectedSourceAddress`, type: `long`
- return type: `boolean`


## Method: checkSingleUse
- parameter: `addr`, type: `long`
- parameter: `varid`, type: `int`
- return type: `java.lang.Long`

Description: 
parameter: addr: 
parameter: varid: 
return: 

## Method: checkSingleUse
- parameter: `addr`, type: `long`
- parameter: `varid`, type: `int`
- parameter: `expectedUseAddress`, type: `long`
- return type: `boolean`


## Method: collectInstructionAllDefs
- parameter: `addr`, type: `long`
- parameter: `r`, type: `java.util.Collection<java.lang.Integer>`


## Method: collectInstructionAllUses
- parameter: `addr`, type: `long`
- parameter: `r`, type: `java.util.Collection<java.lang.Integer>`


## Method: getBlockDefUses
- parameter: `addr`, type: `long`
- parameter: `varid`, type: `int`
- return type: `java.util.Collection<java.lang.Long>`


## Method: getBlockDefUses
- parameter: `addr`, type: `long`
- parameter: `varid`, type: `int`
- parameter: `stopCount`, type: `int`
- return type: `java.util.Collection<java.lang.Long>`


## Method: getBlockUseDefs
- parameter: `addr`, type: `long`
- parameter: `varid`, type: `int`
- return type: `java.util.Collection<java.lang.Long>`


## Method: getCfg
- return type: `com.pnfsoftware.jeb.core.units.code.IControlFlowGraph<InsnType,com.pnfsoftware.jeb.core.units.code.IBasicBlock<InsnType>>`

Description: Retrieve a reference to the CFG object that will be accessed and modified when performing an analysis.
return: 

## Method: getDUI
- parameter: `addr`, type: `long`
- return type: `com.pnfsoftware.jeb.core.units.code.DUI`

Description: 
parameter: addr: 
return: 

## Method: getDUI
- parameter: `a`, type: `com.pnfsoftware.jeb.core.units.code.AddressableInstruction<InsnType>`
- return type: `com.pnfsoftware.jeb.core.units.code.DUI`

Description: 
parameter: a: 
return: 

## Method: getDUI
- parameter: `addr`, type: `long`
- parameter: `insn`, type: `InsnType`
- return type: `com.pnfsoftware.jeb.core.units.code.DUI`

Description: 
parameter: addr: 
parameter: insn: 
return: 

## Method: getDefUseChains
- parameter: `addr`, type: `long`
- return type: `java.util.Map<java.lang.Integer,java.util.Collection<java.lang.Long>>`


## Method: getDefUses
- parameter: `addr`, type: `long`
- parameter: `varid`, type: `int`
- return type: `java.util.Collection<java.lang.Long>`

Description: 
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<java.lang.Long>`

Description: 
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<java.lang.Long>`

Description: 
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<java.lang.Integer,java.util.Collection<java.lang.Long>>`


## Method: getInputMap
- parameter: `varid`, type: `int`
- return type: `java.util.Collection<java.lang.Long>`


## Method: getInputs
- return type: `java.util.Collection<java.lang.Integer>`


## Method: getInstructionAllDefs
- parameter: `addr`, type: `long`
- return type: `java.util.Collection<java.lang.Integer>`


## Method: getInstructionAllUses
- parameter: `addr`, type: `long`
- return type: `java.util.Collection<java.lang.Integer>`


## Method: getInstructionDefs
- parameter: `addr`, type: `long`
- return type: `java.util.Collection<java.lang.Integer>`

Description: 
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<java.lang.Integer>`

Description: 
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<java.lang.Integer>`

Description: 
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<java.lang.Integer>`

Description: 
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<java.lang.Integer>`

Description: 
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<InsnType>`
- parameter: `idx`, type: `int`
- parameter: `varid`, type: `int`
- return type: `java.util.Collection<java.lang.Long>`


## Method: getLiveChains
- parameter: `b`, type: `com.pnfsoftware.jeb.core.units.code.IBasicBlock<InsnType>`
- parameter: `idx`, type: `int`
- parameter: `varid`, type: `int`
- parameter: `stopcount`, type: `int`
- return type: `java.util.Collection<java.lang.Long>`


## Method: getLiveChains
- parameter: `b`, type: `com.pnfsoftware.jeb.core.units.code.IBasicBlock<InsnType>`
- parameter: `idx`, type: `int`
- return type: `java.util.Map<java.lang.Integer,java.util.Collection<java.lang.Long>>`


## Method: getMaxBlocks
- return type: `int`

Description: Retrieve the maximum block count used for common DFA operations. See [#setMaxBlocks(int)](#setMaxBlocks(int)) for details.
return: 

## Method: getOutputMap
- parameter: `blk`, type: `com.pnfsoftware.jeb.core.units.code.IBasicBlock<InsnType>`
- return type: `java.util.Map<java.lang.Integer,java.util.Collection<java.lang.Long>>`


## Method: getOutputMap
- parameter: `blk`, type: `com.pnfsoftware.jeb.core.units.code.IBasicBlock<InsnType>`
- parameter: `varid`, type: `int`
- return type: `java.util.Collection<java.lang.Long>`


## Method: getOutputMap
- return type: `java.util.Map<java.lang.Integer,java.util.Collection<java.lang.Long>>`


## Method: getOutputMap
- parameter: `varid`, type: `int`
- return type: `java.util.Collection<java.lang.Long>`


## Method: getOutputs
- parameter: `blk`, type: `com.pnfsoftware.jeb.core.units.code.IBasicBlock<InsnType>`
- return type: `java.util.Collection<java.lang.Integer>`


## Method: getOutputs
- return type: `java.util.Collection<java.lang.Integer>`


## Method: getReachChains
- parameter: `b`, type: `com.pnfsoftware.jeb.core.units.code.IBasicBlock<InsnType>`
- parameter: `idx`, type: `int`
- parameter: `varid`, type: `int`
- return type: `java.util.Collection<java.lang.Long>`


## Method: getReachChains
- parameter: `b`, type: `com.pnfsoftware.jeb.core.units.code.IBasicBlock<InsnType>`
- parameter: `idx`, type: `int`
- parameter: `varid`, type: `int`
- parameter: `stopcount`, type: `int`
- return type: `java.util.Collection<java.lang.Long>`


## Method: getReachChains
- parameter: `b`, type: `com.pnfsoftware.jeb.core.units.code.IBasicBlock<InsnType>`
- parameter: `idx`, type: `int`
- return type: `java.util.Map<java.lang.Integer,java.util.Collection<java.lang.Long>>`


## Method: getUseDefChains
- parameter: `addr`, type: `long`
- return type: `java.util.Map<java.lang.Integer,java.util.Collection<java.lang.Long>>`


## Method: getUseDefs
- parameter: `addr`, type: `long`
- parameter: `varid`, type: `int`
- return type: `java.util.Collection<java.lang.Long>`

Description: 
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<java.lang.Long>`

Description: 
parameter: addr: instruction address
parameter: varid: a variable, which must be used by the provided instruction
parameter: stopCount: 
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<java.lang.Integer>`

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`


## 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<java.lang.Long>`
- parameter: `srccoll`, type: `java.util.Collection<java.lang.Long>`

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<java.lang.Long>`
- 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<InsnType>`
- parameter: `idx`, type: `int`
- parameter: `varid`, type: `int`
- return type: `boolean`


## Method: isAlwaysExamineIrregularFlows
- return type: `boolean`


## Method: isConservative
- return type: `boolean`

Description: Convenience method used to determine whether the variable collection flags are [DefUseInfo#CONSERVATIVE](DefUseInfo#CONSERVATIVE).
return: 

## Method: isIntegrateCalculatedInputRegisters
- return type: `boolean`


## Method: isReaching
- parameter: `b`, type: `com.pnfsoftware.jeb.core.units.code.IBasicBlock<InsnType>`
- parameter: `idx`, type: `int`
- parameter: `varid`, type: `int`
- return type: `boolean`


## Method: isTerminator
- parameter: `blk`, type: `com.pnfsoftware.jeb.core.units.code.IBasicBlock<InsnType>`
- 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: 
parameter: addr: 
parameter: varid: 
return: 

## Method: isValid
- return type: `boolean`

Description: Determine whether the current analysis was performed and is valid.
return: 

## 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<InsnType>`
- parameter: `i0`, type: `int`
- parameter: `b1`, type: `com.pnfsoftware.jeb.core.units.code.IBasicBlock<InsnType>`
- 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<InsnType>`
- parameter: `i0`, type: `int`
- parameter: `b1`, type: `com.pnfsoftware.jeb.core.units.code.IBasicBlock<InsnType>`
- 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: 
parameter: maxBlocks: optional maximum count of blocks to be explored before failing
return: success indicator; null means unknown

## Method: notifyInstructionUpdate
- parameter: `addr`, type: `long`


## 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: 
parameter: enabled: 
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: 
parameter: enabled: 
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: 
parameter: provider: 
return: the previously set provider

