Struct EvmCompiler 

pub struct EvmCompiler<B>
where
    B: Backend,
{

    name: Option<String>,
    backend: B,
    out_dir: Option<PathBuf>,
    config: FcxConfig,
    builtins: Builtins<B>,
    gas_params: Option<GasParams>,
    dedup: bool,
    dse: bool,
    dump_assembly: bool,
    dump_unopt_assembly: bool,
    compiler_gas_limit: u64,
    remarks: Remarks,
    compiled_sizes: Vec<(String, usize)>,
    finalized: bool,
}

EVM bytecode compiler.

This currently represents one single-threaded IR context and module, which can be used to compile multiple functions as JIT or AOT.

Functions can be incrementally added with translate, and then either written to an object file with write_object when in AOT mode, or JIT-compiled with jit_function.

Performing either of these operations finalizes the module, and no more functions can be added afterwards until clear is called, which will reset the module to its initial state.

Fields

name: Option<String>

backend: B

out_dir: Option<PathBuf>

config: FcxConfig

builtins: Builtins<B>

gas_params: Option<GasParams>

dedup: bool

dse: bool

dump_assembly: bool

dump_unopt_assembly: bool

compiler_gas_limit: u64

remarks: Remarks

compiled_sizes: Vec<(String, usize)>

finalized: bool

Implementations

impl EvmCompiler<EvmLlvmBackend>

pub fn new_llvm(aot: bool) -> Result<EvmCompiler<EvmLlvmBackend>, Report>

Available on crate feature llvm only.

Creates a new instance of the compiler with the LLVM backend.

impl<B> EvmCompiler<B>

where B: Backend,

pub fn new(backend: B) -> EvmCompiler<B>

Creates a new instance of the compiler with the given backend.

pub fn set_module_name(&mut self, name: impl Into<String>)

Sets the name of the module.

pub fn take_timings(&self) -> CompileTimings

Returns the per-phase timing breakdown from the last compilation and resets the counters.

pub fn out_dir(&self) -> Option<&Path>

Returns the output directory.

pub fn set_dump_to(&mut self, output_dir: Option<PathBuf>)

Dumps intermediate outputs and other debug info to the given directory after compilation.

Disables dumping if output_dir is None.

pub fn dump_assembly(&mut self, yes: bool)

Dumps assembly to the output directory.

This can be quite slow.

Defaults to true.

pub fn dump_unopt_assembly(&mut self, yes: bool)

Dumps the unoptimized assembly to the output directory.

This can be quite slow.

Defaults to false.

pub fn opt_level(&self) -> OptimizationLevel

Returns the optimization level.

pub fn set_opt_level(&mut self, level: OptimizationLevel)

Sets the optimization level.

Note that some backends may not support setting the optimization level after initialization.

Defaults to the backend’s initial optimization level.

pub fn debug_assertions(&mut self, yes: bool)

Sets whether to enable debug assertions.

These are useful for debugging, but they do a moderate performance penalty due to the insertion of extra checks and removal of certain assumptions.

Defaults to cfg!(debug_assertions).

pub fn set_dedup(&mut self, yes: bool)

Enables the block deduplication pass.

Defaults to true.

pub fn set_dse(&mut self, yes: bool)

Enables the dead store elimination pass.

Defaults to true.

pub fn debug_support(&self) -> bool

Returns whether JIT debug support is enabled.

Registers JIT objects with debuggers via __jit_debug_register_code, allowing GDB/LLDB to resolve JIT-compiled function names and set breakpoints.

This setting is applied once per process on first JIT compilation. Subsequent compilers inherit the value set by the first.

Defaults to true.

pub fn set_debug_support(&mut self, yes: bool)

Sets whether to enable JIT debug support.

This setting is applied once per process on first JIT compilation. Subsequent compilers inherit the value set by the first.

pub fn profiling_support(&self) -> bool

Returns whether JIT profiling support is enabled.

Installs the LLVM PerfSupportPlugin which writes jitdump records, allowing profilers to resolve JIT-compiled symbols with debug and unwind info.

This setting is applied once per process on first JIT compilation. Subsequent compilers inherit the value set by the first.

Defaults to false.

pub fn set_profiling_support(&mut self, yes: bool)

Sets whether to enable JIT profiling support.

This setting is applied once per process on first JIT compilation. Subsequent compilers inherit the value set by the first.

pub fn simple_perf(&self) -> bool

Returns whether the simple perf map plugin is enabled.

Writes /tmp/perf-<pid>.map in the perf map format so that profilers can resolve JIT-compiled symbols without the jitdump machinery.

Not suitable for long-running programs. The map file is append-only and never cleaned up, so entries for freed JIT code accumulate indefinitely. Prefer set_profiling_support (jitdump) for long-lived processes.

This setting is applied once per process on first JIT compilation. Subsequent compilers inherit the value set by the first.

Defaults to true.

pub fn set_simple_perf(&mut self, yes: bool)

Sets whether to enable the simple perf map plugin.

This setting is applied once per process on first JIT compilation. Subsequent compilers inherit the value set by the first.

pub fn set_debug_info(&mut self, yes: bool)

Sets whether to enable debug info emission.

Debug info embeds DWARF metadata and annotates IR/assembly dumps with source locations from the parsed bytecode.

Automatically enabled by set_dump_to.

Defaults to false.

pub fn frame_pointers(&mut self, yes: bool)

Sets whether to enable frame pointers.

This is useful for profiling and debugging, but it incurs a very slight performance penalty.

Enabled by default in debug builds, when -Cforce-frame-pointers is set, or when set_dump_to is called with a directory.

pub fn inspect_stack(&mut self, yes: bool)

Sets whether to treat the stack as observable outside the function.

If this is set to true, the stack length must be passed in the arguments.

This is useful to inspect the stack after the function has been executed, but it does incur a performance penalty as the stack will be stored at all return sites.

Defaults to false.

pub unsafe fn stack_bound_checks(&mut self, yes: bool)

Sets whether to enable stack bound checks.

Defaults to true.

Safety

Removing stack length checks may improve compilation speed and performance, but will result in undefined behavior if the stack length overflows at runtime, rather than a StackUnderflow/StackOverflow result.

pub fn set_compiler_gas_limit(&mut self, limit: u64)

Sets the gas budget for compile-time evaluation of user-supplied bytecode.

The compiler evaluates EVM operations at compile time during analysis passes. Without a budget, adversarial bytecode (e.g. many EXP) can make compilation arbitrarily slow. This limit uses the EVM gas schedule to bound work.

When the budget is exhausted, further evaluation is skipped and values remain dynamic.

Defaults to 100k gas. Set to 0 to disable compile-time evaluation entirely, or u64::MAX to disable the limit.

pub fn gas_metering(&mut self, yes: bool)

Sets whether to track gas costs.

Disabling this will greatly improves compilation speed and performance, at the cost of not being able to check for gas exhaustion.

Note that this does not disable gas usage in certain instructions, mainly the ones that are implemented as builtins.

Use with care, as executing a function with gas disabled may result in an infinite loop.

Defaults to true.

pub fn single_error(&mut self, yes: bool)

Sets whether to collapse every JIT failure path to a single OutOfGas constant.

Failures (stack under/overflow, invalid jump, real OOG, invalid opcode, etc.) are semantically interchangeable for callers that only branch on success vs failure, so this lets LLVM DCE the per-failure-site materialization and the failure-block phi. Successful exits (STOP/RETURN/REVERT) keep their original codes.

Useful for benchmarking the cost of failure-result materialization.

Defaults to true.

pub fn set_gas_params(&mut self, gas_params: GasParams)

Sets custom gas parameters.

Overrides the default gas schedule derived from the spec_id. Useful for custom chains or hardforks with non-standard gas costs.

Defaults to GasParams::new_spec(spec_id).

pub fn translate<'a>( &mut self, name: &str, input: impl Into<EvmCompilerInput<'a>>, spec_id: SpecId, ) -> Result<<B as Backend>::FuncId, Report>

Translates the given EVM bytecode into an internal function.

NOTE: name must be unique for each function, as it is used as the name of the final symbol.

pub unsafe fn jit<'a>( &mut self, name: &str, bytecode: impl Into<EvmCompilerInput<'a>>, spec_id: SpecId, ) -> Result<EvmCompilerFn, Report>

(JIT) Compiles the given EVM bytecode into a JIT function.

See translate for more information.

Safety

The returned function pointer is owned by the module, and must not be called after the module is cleared or the function is freed.

pub unsafe fn jit_function( &mut self, id: <B as Backend>::FuncId, ) -> Result<EvmCompilerFn, Report>

(JIT) Finalizes the module and JITs the given function.

Safety

The returned function pointer is owned by the module, and must not be called after the module is cleared or the function is freed.

pub fn write_object_to_file(&mut self, path: &Path) -> Result<(), Report>

(AOT) Writes the compiled object to the given file.

pub fn write_object<W>(&mut self, w: W) -> Result<(), Report>

where W: Write,

(AOT) Finalizes the module and writes the compiled object to the given writer.

pub unsafe fn free_function( &mut self, id: <B as Backend>::FuncId, ) -> Result<(), Report>

(JIT) Frees the memory associated with a single function.

Note that this will not reset the state of the internal module even if all functions are freed with this function. Use clear to reset the module.

Safety

Because this function invalidates any pointers retrieved from the corresponding module, it should only be used when none of the functions from that module are currently executing and none of the fn pointers are called afterwards.

pub fn clear_ir(&mut self) -> Result<(), Report>

Clears the IR module, freeing memory used by IR representations.

This does not free JIT-compiled machine code, so previously obtained function pointers remain valid. The module is left in a state where new functions can be translated.

pub unsafe fn clear(&mut self) -> Result<(), Report>

Frees all functions and resets the state of the internal module, allowing for new functions to be compiled.

Safety

Because this function invalidates any pointers retrieved from the corresponding module, it should only be used when none of the functions from that module are currently executing and none of the fn pointers are called afterwards.

Trait Implementations

impl<B> Debug for EvmCompiler<B>

where B: Backend,

fn fmt(&self, __derive_more_f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

Layout

Note: Unable to compute type layout, possibly due to this type having generic parameters. Layout can only be computed for concrete, fully-instantiated types.