angr.analyses.decompiler.known_patterns.dsl

Declarative pattern-AST for describing known AIL code idioms (KnownPatterns).

Pattern nodes are frozen dataclasses that structurally match AIL expressions and statements. Every node accepts an optional name: a named capture. When the same capture name occurs more than once in a pattern, all occurrences must bind .likes()-equal expressions (unification).

Matching is performed by calling PatternNode.match() with a MatchState (the bindings environment) and a MatchCtx (matcher-wide flags and callbacks). Match methods are functional: they return a new MatchState on success and None on failure, so alternatives (commutative operand orders, PChoice) can backtrack by reusing the pre-branch state.

class angr.analyses.decompiler.known_patterns.dsl.MatchState

Bases: object

The bindings environment threaded through a match attempt.

bindings: dict[str, Expression]
consumed_stmt_idxs: frozenset[int] = frozenset({})
chased_defs: tuple[tuple[int, int], ...] = ()
remote_defs: tuple[tuple[int, Expression], ...] = ()
skipped_converts: tuple[Convert | Reinterpret, ...] = ()
base_aliases: tuple[tuple[int, int, int], ...] = ()
bind(name, expr)

Bind name to expr; on rebind, require .likes() equality.

Return type:

MatchState | None

Parameters:
__init__(bindings=<factory>, consumed_stmt_idxs=frozenset({}), chased_defs=(), remote_defs=(), skipped_converts=(), base_aliases=())
Parameters:
Return type:

None

class angr.analyses.decompiler.known_patterns.dsl.MatchCtx

Bases: object

Matcher-wide flags and callbacks.

ptr_bits: int | None = None
skip_conversions: bool = True
skip_conversions_at_leaves: bool = False

also step over Convert wrappers right above a variable or constant leaf. The exact library keeps this off: its patterns spell out the conversions they expect. A pattern lifted from a selection has had them dropped, since the generator mirrors the structural nodes’ skipping, so it needs the leaves to skip as well or it cannot match the statements it came from.

chase_fn: Callable[[int], tuple[int, Expression] | None] | None = None
peek_fn: Callable[[int], Expression | None] | None = None
remote_chase_fn: Callable[[int], Expression | None] | None = None
stack_slot_fn: Callable[[int], VirtualVariable | None] | None = None
call_target_fn: Callable[[Call], frozenset[str]] | None = None
next_idx()
Return type:

int

def_fn: Callable[[int], Expression | None] | None = None
symbol_addr_fn: Callable[[str], int | None] | None = None
__init__(ptr_bits=None, skip_conversions=True, skip_conversions_at_leaves=False, chase_fn=None, peek_fn=None, remote_chase_fn=None, stack_slot_fn=None, call_target_fn=None, next_idx=<function _standalone_idx>, def_fn=None, symbol_addr_fn=None)
Parameters:
Return type:

None

class angr.analyses.decompiler.known_patterns.dsl.PatternNode

Bases: object

Base class of all pattern nodes.

class angr.analyses.decompiler.known_patterns.dsl.PatternExpr

Bases: PatternNode

Base class of expression patterns.

match(expr, state, ctx)
Return type:

MatchState | None

Parameters:
class angr.analyses.decompiler.known_patterns.dsl.PAny

Bases: PatternExpr

Matches any expression.

name: str | None = None
bits: int | None = None
match(expr, state, ctx)
Return type:

MatchState | None

Parameters:
__init__(name=None, bits=None)
Parameters:
  • name (str | None)

  • bits (int | None)

Return type:

None

class angr.analyses.decompiler.known_patterns.dsl.PVVar

Bases: PatternExpr

Matches a VirtualVariable.

name: str | None = None
bits: int | None = None
categories: frozenset[VirtualVariableCategory] | None = None
match(expr, state, ctx)
Return type:

MatchState | None

Parameters:
__init__(name=None, bits=None, categories=None)
Parameters:
  • name (str | None)

  • bits (int | None)

  • categories (frozenset[VirtualVariableCategory] | None)

Return type:

None

class angr.analyses.decompiler.known_patterns.dsl.PConst

Bases: PatternExpr

Matches a Const, by exact value or by predicate. Width is ignored unless bits is given (e.g. shift amounts are often 8-bit).

value: int | None = None
pred: Callable[[int], bool] | None = None
bits: int | None = None
name: str | None = None
values: frozenset[int] | None = None

an enumerable set of acceptable values. Prefer this over pred when the set is known: the finder indexes patterns by the constants they accept, so a pattern is only tried where one of its constants occurs.

symbol: str | None = None

the address of this symbol in the binary being matched, resolved through MatchCtx.symbol_addr_fn; the portable spelling of a global’s address

match(expr, state, ctx)
Return type:

MatchState | None

Parameters:
__init__(value=None, pred=None, bits=None, name=None, values=None, symbol=None)
Parameters:
Return type:

None

class angr.analyses.decompiler.known_patterns.dsl.PBinOp

Bases: PatternExpr

Matches a BinaryOp. op may be a single op string or a set of acceptable ops. Commutative ops try both operand orders unless commutative is explicitly False.

op: str | frozenset[str]
operands: tuple[PatternExpr, PatternExpr]
commutative: bool | None = None
name: str | None = None
match(expr, state, ctx)
Return type:

MatchState | None

Parameters:
__init__(op, operands, commutative=None, name=None)
Parameters:
Return type:

None

class angr.analyses.decompiler.known_patterns.dsl.PUnaryOp

Bases: PatternExpr

Matches a UnaryOp.

op: str | frozenset[str]
operand: PatternExpr
name: str | None = None
match(expr, state, ctx)
Return type:

MatchState | None

Parameters:
__init__(op, operand, name=None)
Parameters:
Return type:

None

class angr.analyses.decompiler.known_patterns.dsl.PConv

Bases: PatternExpr

Matches a Convert explicitly (never skipped).

operand: PatternExpr
from_bits: int | None = None
to_bits: int | None = None
name: str | None = None
match(expr, state, ctx)
Return type:

MatchState | None

Parameters:
__init__(operand, from_bits=None, to_bits=None, name=None)
Parameters:
Return type:

None

class angr.analyses.decompiler.known_patterns.dsl.PReinterpret

Bases: PatternExpr

Matches a Reinterpret explicitly (never skipped): the bit pattern of a floating-point value read as an integer (from_type="F"), or an integer’s bits viewed as a floating-point value (from_type="I").

operand: PatternExpr
from_type: str | None = None
name: str | None = None
match(expr, state, ctx)
Return type:

MatchState | None

Parameters:
__init__(operand, from_type=None, name=None)
Parameters:
Return type:

None

class angr.analyses.decompiler.known_patterns.dsl.PExtract

Bases: PatternExpr

Matches an Extract, a bit-slice of a wider value.

This is how a scalar reaches integer code out of a vector register when the 128-bit op did not get narrowed away: movq %xmm2,%rax on a value that came from maxsd/mulsd lifts to Extract(vvar_128, 64bits@0) rather than to a Convert. Without a node for it, every libm bit-twiddle whose operand is a computed double rather than an incoming argument is unmatchable.

bits/offset default to unconstrained; offset is in bits.

operand: PatternExpr
bits: int | None = None
offset: int | None = None
name: str | None = None
match(expr, state, ctx)
Return type:

MatchState | None

Parameters:
__init__(operand, bits=None, offset=None, name=None)
Parameters:
Return type:

None

class angr.analyses.decompiler.known_patterns.dsl.PLoad

Bases: PatternExpr

Matches a memory Load. size is in bytes.

addr: PatternExpr
size: int | None = None
name: str | None = None
match(expr, state, ctx)
Return type:

MatchState | None

Parameters:
__init__(addr, size=None, name=None)
Parameters:
Return type:

None

class angr.analyses.decompiler.known_patterns.dsl.PCall

Bases: PatternExpr

Matches a Call whose callee is one of names.

The callee is what makes a pattern containing this node self-guarding: an idiom spelled around a named runtime function (operator delete in the std::string destructor, __ctype_b_loc in isspace) cannot be confused with arithmetic that happens to look alike, because no other code calls that function to do something else.

names is matched against every spelling the callee is known by (the raw symbol and its demangled form), so a pattern may name either. Prefer the mangled spelling: it is exact, while a demangled one carries the argument list and varies with the demangler.

args=None leaves the arguments unconstrained; a tuple constrains them positionally, with None in a slot meaning “any expression”.

names: frozenset[str]
args: tuple[PatternExpr | None, ...] | None = None
name: str | None = None
match(expr, state, ctx)
Return type:

MatchState | None

Parameters:
__init__(names, args=None, name=None)
Parameters:
Return type:

None

class angr.analyses.decompiler.known_patterns.dsl.PCallResult

Bases: PatternExpr

The value a call to one of names returned.

A call’s result is rarely used where it is produced: the compiler assigns it to a register and reads that register, often in another block. __ctype_b_loc() is called once per function and its table indexed at every predicate. So this node matches the virtual variable and looks up its definition read-only. Nothing is consumed, moved or recomputed; the call stays where the compiler put it.

An inline Call expression is matched too, for the case where the value is used at its definition.

names: frozenset[str]
name: str | None = None
match(expr, state, ctx)
Return type:

MatchState | None

Parameters:
__init__(names, name=None)
Parameters:
Return type:

None

class angr.analyses.decompiler.known_patterns.dsl.PDefOf

Bases: PatternExpr

inner, or a virtual variable whose reaching definition is inner.

The compiler is free to compute a value once and use it twice, and it does so exactly where an idiom uses one value twice. if (_M_p != &_M_local_buf) operator delete(_M_p, ...) reads _M_p in the compare and in the call, so gcc loads it into a register and the pattern sees Load(s) in neither place; it sees the same virtual variable in both.

Reading that variable’s definition is read-only. Nothing is consumed, moved or recomputed, and the identification stays accurate even if memory changes afterwards: the variable holds what the load produced at the definition, which is what the idiom meant. That is why this is not peek_fn, whose contract (“can be recomputed at the use”) a load cannot satisfy.

The unconsumed definition is left where it was, so a region that matches through this node keeps it as residue. That is harmless, and dead-code elimination removes it once the idiom’s other uses are gone.

inner: PatternExpr
name: str | None = None
match(expr, state, ctx)
Return type:

MatchState | None

Parameters:
__init__(inner, name=None)
Parameters:
Return type:

None

class angr.analyses.decompiler.known_patterns.dsl.PField

Bases: PatternExpr

The address of the field at offset inside the object bound to base.

Spelling a container’s fields as PLoad(PVVar("v")) / PLoad(PVVar("v") + 8) requires the object to sit at the very address held in a virtual variable. That is the minority case: measured over the benchmark corpus, only 10-25% of the DWARF sites for a std::vector accessor read the container through a bare pointer; the rest reach it as a field of something else (this->tokens.size()), which lifts to Load(this + 56) / Load(this + 64) and cannot bind v at all.

PField matches such an address and binds base to the object’s own address: root when the object is at offset 0, else root + K. Two fields of one object therefore unify on K, which is what keeps the node honest: it replaces the constraint “this displacement is exactly 8” with “these two displacements differ by exactly 8”.

Only use it in patterns that reference at least two fields. With a single field there is no second displacement to constrain, so PLoad(PField("s", 8)) degenerates into “any load through a pointer plus a non-negative constant” and matches essentially everything.

root must be a virtual variable: the outliner materializes tmp = root + K ahead of the region so the synthesized call still takes a variable.

base: str
offset: int
name: str | None = None
match(expr, state, ctx)
Return type:

MatchState | None

Parameters:
__init__(base, offset, name=None)
Parameters:
Return type:

None

class angr.analyses.decompiler.known_patterns.dsl.PStackField

Bases: PatternExpr

A field of a container that lives on the stack.

A stack object never reaches the matcher as an object at all: variable recovery has already split it into one virtual variable per slot, so std::string s; is a handful of independent vvar{s-112}, vvar{s-96} and there is no Load(s) to match and no s + 16 to compare against. Measured over the benchmark corpus (kp-eval/stack_share.py), stack objects are 40-54% of the DWARF sites for std::string::length and 15-35% for std::vector<T>::size.

This node matches the slot of the field at offset and binds base to the object’s own stack offset, so two fields of one object unify on it exactly as PField’s two displacements do. as_address matches the address form (&slot, which lifts to UnaryOp("Reference", vvar)) rather than the value form; std::string::capacity needs both, since it compares the data pointer against the address of the local buffer.

The binding is a StackBaseOffset, the object’s own address. That is both the thing two fields must agree on and, directly, the argument the synthesized call takes, so nothing has to be materialized for it.

Matching is only half the problem, and the other half is why a pattern using this node is never outlined: the region for a stack container reads N independent slots, so its live-ins are N values rather than one pointer and there is nothing for a synthesized callee to take. Such a match is instead rewritten in place: the matched expression, or the whole region, is replaced by call(&s), whose argument the binding already is. See KnownPatternFinder._rewrite_in_place and _rewrite_graph_in_place.

base: str
offset: int
as_address: bool = False
size: int | None = None
name: str | None = None
match(expr, state, ctx)
Return type:

MatchState | None

Parameters:
__init__(base, offset, as_address=False, size=None, name=None)
Parameters:
Return type:

None

class angr.analyses.decompiler.known_patterns.dsl.PPhi

Bases: PatternExpr

Matches a Phi expression, capturing it whole (its individual sources are not matched). Useful for loop-header blocks, whose statements are phi assignments.

name: str | None = None
bits: int | None = None
match(expr, state, ctx)
Return type:

MatchState | None

Parameters:
__init__(name=None, bits=None)
Parameters:
  • name (str | None)

  • bits (int | None)

Return type:

None

class angr.analyses.decompiler.known_patterns.dsl.PITE

Bases: PatternExpr

Matches an ITE (ternary) expression cond ? iftrue : iffalse.

Needed because ITERegionConverter (AFTER_GLOBAL_SIMPLIFICATION) collapses if (c) x = a; else x = b; diamonds into a single ITE assignment before the KnownPatternOutliner runs, so a two-armed value-select idiom reaches the outliner as an expression, not as a PGraphPat region. (A triangle, with one arm empty as in the MSVC std::string::c_str SSO select, is not converted, which is why that idiom is still a PGraphPat.)

cond: PatternExpr
iftrue: PatternExpr
iffalse: PatternExpr
name: str | None = None
match(expr, state, ctx)
Return type:

MatchState | None

Parameters:
__init__(cond, iftrue, iffalse, name=None)
Parameters:
Return type:

None

class angr.analyses.decompiler.known_patterns.dsl.PChoice

Bases: PatternExpr

Ordered alternation: matches the first alternative that succeeds.

alternatives: tuple[PatternExpr, ...]
__init__(*alternatives)
Parameters:

alternatives (PatternExpr)

match(expr, state, ctx)
Return type:

MatchState | None

Parameters:
class angr.analyses.decompiler.known_patterns.dsl.PatternStmt

Bases: PatternNode

Base class of statement patterns.

match(stmt, state, ctx)
Return type:

MatchState | None

Parameters:
class angr.analyses.decompiler.known_patterns.dsl.PAssign

Bases: PatternStmt

Matches an Assignment statement.

dst: PatternExpr
src: PatternExpr
optional: bool = False

the statement may be absent from an occurrence

Type:

fuzzy matching only

weight: float = 1.0

relative contribution to an occurrence’s score

Type:

fuzzy matching only

match(stmt, state, ctx)
Return type:

MatchState | None

Parameters:
__init__(dst, src, *, optional=False, weight=1.0)
Parameters:
Return type:

None

class angr.analyses.decompiler.known_patterns.dsl.PStore

Bases: PatternStmt

Matches a Store statement. size is in bytes.

addr: PatternExpr
value: PatternExpr
size: int | None = None
optional: bool = False

the statement may be absent from an occurrence

Type:

fuzzy matching only

weight: float = 1.0

relative contribution to an occurrence’s score

Type:

fuzzy matching only

match(stmt, state, ctx)
Return type:

MatchState | None

Parameters:
__init__(addr, value, size=None, *, optional=False, weight=1.0)
Parameters:
Return type:

None

class angr.analyses.decompiler.known_patterns.dsl.PCallStmt

Bases: PatternStmt

Matches a statement whose effect is a call.

Ailment has no Call statement: a call whose result is discarded is a SideEffectStatement wrapping the Call expression, and one whose result is kept is an ordinary Assignment. Both spellings are the same idiom, so both match; dst, when given, also constrains the assigned destination, which requires the assignment form.

call: PCall
dst: PatternExpr | None = None
optional: bool = False

the statement may be absent from an occurrence

Type:

fuzzy matching only

weight: float = 1.0

relative contribution to an occurrence’s score

Type:

fuzzy matching only

match(stmt, state, ctx)
Return type:

MatchState | None

Parameters:
__init__(call, dst=None, *, optional=False, weight=1.0)
Parameters:
Return type:

None

class angr.analyses.decompiler.known_patterns.dsl.PCondJump

Bases: PatternStmt

Matches a ConditionalJump, matching its condition expression.

condition: PatternExpr
optional: bool = False

the statement may be absent from an occurrence

Type:

fuzzy matching only

weight: float = 1.0

relative contribution to an occurrence’s score

Type:

fuzzy matching only

match(stmt, state, ctx)
Return type:

MatchState | None

Parameters:
__init__(condition, *, optional=False, weight=1.0)
Parameters:
Return type:

None

class angr.analyses.decompiler.known_patterns.dsl.PAnyStmt

Bases: PatternStmt

Matches any single statement. The statement-level counterpart of PAny: a placeholder for “something happens here” whose exact form the pattern does not care about.

optional: bool = False
weight: float = 1.0
match(stmt, state, ctx)
Return type:

MatchState | None

Parameters:
__init__(*, optional=False, weight=1.0)
Parameters:
Return type:

None

class angr.analyses.decompiler.known_patterns.dsl.PReturn

Bases: PatternStmt

Matches a Return. values constrains the returned expressions, one pattern each; None matches a return of any arity.

values: tuple[PatternExpr, ...] | None = None
optional: bool = False
weight: float = 1.0
match(stmt, state, ctx)
Return type:

MatchState | None

Parameters:
__init__(values=None, *, optional=False, weight=1.0)
Parameters:
Return type:

None

class angr.analyses.decompiler.known_patterns.dsl.PStmtSeq

Bases: PatternStmt

Matches a group of statements within one block. When ordered (the default), the statement patterns must match in order; with allow_gaps, unrelated statements may sit between the matched ones. When ordered is False, the statement patterns match statements of the block in any order (each pattern to a distinct statement), which suits idioms whose statement order the compiler chooses freely (e.g. list-link stores).

stmts: tuple[PatternStmt, ...]
allow_gaps: bool = True
ordered: bool = True
max_gap: int = 8

How many unmatched statements may sit between two matched ones. Without a bound the scan runs to the end of the block from every statement it could start at, quadratic per block per template, and finds nothing: an idiom’s statements are adjacent apart from what the scheduler interleaved, which is a handful of instructions rather than a basic block.

__init__(stmts, allow_gaps=True, ordered=True, max_gap=8)
Parameters:
Return type:

None

class angr.analyses.decompiler.known_patterns.dsl.PBlockPat

Bases: PatternNode

A labeled block of statements in a multi-block pattern graph. An empty stmts sequence matches any block (structure alone identifies it).

label: str
stmts: PStmtSeq
__init__(label, stmts)
Parameters:
Return type:

None

class angr.analyses.decompiler.known_patterns.dsl.PGraphPat

Bases: PatternNode

A multi-block pattern: labeled blocks connected by edges.

blocks maps a label to its PBlockPat. edges are (src_label, dst_label) pairs; a destination label that does not appear in blocks denotes an external successor, a region exit that becomes the Outliner frontier. entry is the label of the single entry block. Captures unify across all blocks (one bindings environment).

blocks: dict[str, PBlockPat]
edges: Sequence[tuple[str, str]]
entry: str
property external_labels: set[str]
__init__(blocks, edges, entry)
Parameters:
Return type:

None

angr.analyses.decompiler.known_patterns.dsl.LeafStmt = angr.analyses.decompiler.known_patterns.dsl.PAssign | angr.analyses.decompiler.known_patterns.dsl.PStore | angr.analyses.decompiler.known_patterns.dsl.PCallStmt | angr.analyses.decompiler.known_patterns.dsl.PCondJump | angr.analyses.decompiler.known_patterns.dsl.PReturn | angr.analyses.decompiler.known_patterns.dsl.PAnyStmt

The statement patterns that stand for one concrete statement, and so are the ones a fuzzy occurrence can score, skip or weight.

angr.analyses.decompiler.known_patterns.dsl.iter_stmt_patterns(node)

Every leaf statement pattern under node, in pattern order.

Return type:

Iterator[PAssign | PStore | PCallStmt | PCondJump | PReturn | PAnyStmt]

Parameters:

node (PatternNode)

angr.analyses.decompiler.known_patterns.dsl.has_fuzzy_nodes(node)

Whether node can only be matched by the fuzzy matcher.

An optional statement has no meaning to the exact matcher, which either finds every statement pattern or fails; a pattern carrying one has to be kept away from it rather than silently matched as if the statement were required.

Return type:

bool

Parameters:

node (PatternNode)

angr.analyses.decompiler.known_patterns.dsl.pattern_anchor_key(node)

A cheap discriminator of the pattern root, used to prune candidate patterns at each expression position: (ail kind, op or None).

Returns None when the root is not discriminating (PAny/PChoice/…), in which case the pattern must be attempted everywhere.

Return type:

tuple[str, str | None] | None

Parameters:

node (PatternNode)

angr.analyses.decompiler.known_patterns.dsl.pattern_index_keys(node)

Every (ail kind, op or None, constant operand or None) an occurrence of node can start with; None when the root is not discriminating.

Finer than pattern_anchor_key() in three ways. A set-valued op is expanded into one key per op rather than dropped to “any op”. A PChoice is the union of its alternatives’ keys, not “anywhere” unless one alternative truly is. And a binary op with a PConst operand whose values are enumerable (value or values) carries each such value as a third component: a PConst only matches a literal Const, so a Mul(x, magic) pattern need not be tried at a multiply by any other constant. The generated std::vector<T>::size family is a thousand such patterns keyed on Mul, and without this every multiply in a function tried all of them.

Return type:

list[tuple[str, str | None, int | None]] | None

Parameters:

node (PatternNode)

angr.analyses.decompiler.known_patterns.dsl.expr_const_operands(expr)

The literal constants among a binary op’s operands (through Converts), for the index lookup.

Return type:

tuple[int, ...]

Parameters:

expr (Expression)

angr.analyses.decompiler.known_patterns.dsl.stmt_pattern_anchor_key(node)

The discriminator of a statement pattern’s first statement.

Statement patterns are anchored at every statement of every block and then scan forward, so trying one that cannot possibly match is the expensive kind of waste. The key is the statement kind plus the anchor key of the expression that carries the pattern’s shape (an assignment’s source, a store’s value), which is what separates t = *a (a swap) from the assignments that make up most of a block.

Return type:

tuple[str, tuple[str, str | None] | None] | None

Parameters:

node (PatternNode)

angr.analyses.decompiler.known_patterns.dsl.stmt_anchor_key(stmt)

The anchor key of a concrete AIL statement, for pruning.

Return type:

tuple[str, tuple[str, str | None] | None]

Parameters:

stmt (Statement)

angr.analyses.decompiler.known_patterns.dsl.expr_anchor_key(expr)

The anchor key of a concrete AIL expression, for pruning.

Return type:

tuple[str, str | None]

Parameters:

expr (Expression)