Skip to main content

Module edgecov

Module edgecov 

Source
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.
EdgeCovGuard
Executes the instrumentation opcodes on this thread while alive, recording edge hits when edges is set and comparison operands when cmp_log is set.
EdgeHits πŸ”’
Hit counters of one call, indexed by edge ID.
InstrumentedConfig πŸ”’
The base opcode table of BASE_SPEC_ID with the instrumentation opcodes.
InstrumentedEdgeHit
One instrumented edge hit during a call: its ID and AFL-style hit counter.
SiteCmpLog πŸ”’
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 CMPLOG instruction: pops site << 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 the PUSH gas.
edgecov πŸ”’
The EDGECOV instruction: pops the edge ID, records the hit and refunds the PUSH gas.

ConstantsΒ§

CMPLOG πŸ”’
The CMPLOG opcode byte.
EDGECOV πŸ”’
The EDGECOV opcode 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 PUSHn that precedes every EDGECOV or CMPLOG, 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 EDGECOV and CMPLOG instructions to config.
with_state πŸ”’