Expand description
Compiler-instrumented edge coverage and comparison logging through the EDGECOV and CMPLOG
opcodes.
Coverage builds of a compiler emit PUSHn <id>; EDGECOV on every control-flow edge and
PUSHn <site << 8 | cmp opcode>; CMPLOG right before every EQ, LT, GT, SLT and SGT.
Both opcodes are otherwise undefined. Foundryβs EVMs carry them in their opcode tables, but
they fail as undefined opcodes unless an EdgeCovGuard is alive on the thread.
While it is, EDGECOV pops the edge ID and bumps its AFL NeverZero hit counter, and CMPLOG
pops its tag and records the two words below it, the operands of the comparison that follows.
Both refund the 3 gas of the PUSH the compiler emits before them, so a probe costs no gas
once it ran. Hits and operands are kept per thread in dense tables indexed by ID, and taken
once the call ends.
Re-exportsΒ§
use alloy_primitives::Address;πuse alloy_primitives::U256;πuse evm2::EvmConfig;πuse evm2::ExecutionConfig;πuse evm2::OpcodeConfig;πuse evm2::SpecId;πuse evm2::Version;πuse evm2::interpreter::InstrStop;πuse evm2::interpreter::op;πuse evm2_macros::instruction;πuse std::cell::UnsafeCell;πuse std::marker::PhantomData;π
StructsΒ§
- CmpOperands
- A comparison operand pair captured during execution.
- Edge
CovGuard - Executes the instrumentation opcodes on this thread while alive, recording edge hits when
edgesis set and comparison operands whencmp_logis set. - Edge
Hits π - Hit counters of one call, indexed by edge ID.
- Instrumented
Config π - The base opcode table of
BASE_SPEC_IDwith the instrumentation opcodes. - Instrumented
Edge Hit - One instrumented edge hit during a call: its ID and AFL-style hit counter.
- Site
CmpLog π - Comparison operands of one call, with the cmp-log inspectorβs caps counted per site ID in a dense table. Unlike the inspector, copies of a contract at several addresses share their caps.
- State π
- This threadβs instrumentation state.
- cmplog π
- The
CMPLOGinstruction: popssite << 8 | cmp opcode, records the two words below it as the operands of that comparison, with the site ID as the program counter, and refunds thePUSHgas. - edgecov π
- The
EDGECOVinstruction: pops the edge ID, records the hit and refunds thePUSHgas.
ConstantsΒ§
- CMPLOG π
- The
CMPLOGopcode byte. - EDGECOV π
- The
EDGECOVopcode byte. - MAX_
CMP_ LOG_ SITES - Maximum number of unique comparison sites tracked per call for CmpLog-style feedback.
- MAX_
CMP_ OBSERVATIONS_ PER_ SITE - Maximum number of comparison operand pairs tracked per site. This matches the downstream loop detection threshold so a hot loop can be classified without filling the whole log.
- MAX_
EDGE_ πID - Largest edge or comparison site ID that is recorded. IDs are dense from 1, so anything above this is malformed instrumentation and is ignored instead of growing the tables without bound.
- PUSH_
GAS π - Gas of the
PUSHnthat precedes everyEDGECOVorCMPLOG, refunded by the instruction. - STATE π
FunctionsΒ§
- execution_
config π - The execution config of a network that runs the base opcode table, with the instrumentation opcodes.
- probe_
id π - Converts a probeβs ID word, ignoring the reserved ID 0 and IDs above
MAX_EDGE_ID. - take_
cmp_ log - Takes this threadβs comparison operands.
- take_
edges - Takes this threadβs edge hits in first-hit order.
- with_
instrumentation π - Adds the
EDGECOVandCMPLOGinstructions toconfig. - with_
state π