EVMC
EVMC Helpers

EVMC Helpers. More...

Modules

 Result Optional Storage
 Helpers for optional storage of evmc_result.
 

Macros

#define EVMC_EXPORT   __attribute__((visibility("default")))
 Marks a function to be exported from a shared library.
 
#define EVMC_NOEXCEPT
 Safe way of marking a function with noexcept C++ specifier.
 

Functions

static bool evmc_is_abi_compatible (struct evmc_vm *vm)
 Returns true if the VM has a compatible ABI version.
 
static const char * evmc_vm_name (struct evmc_vm *vm)
 Returns the name of the VM.
 
static const char * evmc_vm_version (struct evmc_vm *vm)
 Returns the version of the VM.
 
static bool evmc_vm_has_capability (struct evmc_vm *vm, enum evmc_capabilities capability)
 Checks if the VM has the given capability.
 
static void evmc_destroy (struct evmc_vm *vm)
 Destroys the VM instance.
 
static enum evmc_set_option_result evmc_set_option (struct evmc_vm *vm, char const *name, char const *value)
 Sets the option for the VM, if the feature is supported by the VM.
 
static struct evmc_result evmc_execute (struct evmc_vm *vm, const struct evmc_host_interface *host, struct evmc_host_context *context, enum evmc_revision rev, const struct evmc_message *msg, uint8_t const *code, size_t code_size)
 Executes code in the VM instance.
 
static void evmc_free_result_memory (const struct evmc_result *result)
 The evmc_result release function using free() for releasing the memory.
 
static struct evmc_result evmc_make_result (enum evmc_status_code status_code, int64_t gas_left, int64_t gas_refund, const uint8_t *output_data, size_t output_size)
 Creates the result from the provided arguments.
 
static void evmc_release_result (struct evmc_result *result)
 Releases the resources allocated to the execution result.
 
static const char * evmc_status_code_to_string (enum evmc_status_code status_code)
 Returns text representation of the evmc_status_code.
 
static const char * evmc_revision_to_string (enum evmc_revision rev)
 Returns the name of the evmc_revision.
 

Detailed Description

EVMC Helpers.

A collection of C helper functions for invoking a VM instance methods. These are convenient for languages where invoking function pointers is "ugly" or impossible (such as Go).

Macro Definition Documentation

◆ EVMC_EXPORT

#define EVMC_EXPORT   __attribute__((visibility("default")))

Marks a function to be exported from a shared library.

Definition at line 22 of file utils.h.

◆ EVMC_NOEXCEPT

#define EVMC_NOEXCEPT

Safe way of marking a function with noexcept C++ specifier.

Definition at line 32 of file utils.h.

Function Documentation

◆ evmc_destroy()

static void evmc_destroy ( struct evmc_vm vm)
inlinestatic

Destroys the VM instance.

See also
evmc_destroy_fn

Definition at line 68 of file helpers.h.

69{
70 vm->destroy(vm);
71}
evmc_destroy_fn destroy
Pointer to function destroying the VM instance.
Definition: evmc.h:1170

◆ evmc_execute()

static struct evmc_result evmc_execute ( struct evmc_vm vm,
const struct evmc_host_interface host,
struct evmc_host_context context,
enum evmc_revision  rev,
const struct evmc_message msg,
uint8_t const *  code,
size_t  code_size 
)
inlinestatic

Executes code in the VM instance.

See also
evmc_execute_fn.

Definition at line 92 of file helpers.h.

99{
100 return vm->execute(vm, host, context, rev, msg, code, code_size);
101}
evmc_execute_fn execute
Pointer to function executing a code by the VM instance.
Definition: evmc.h:1177

◆ evmc_free_result_memory()

static void evmc_free_result_memory ( const struct evmc_result result)
static

The evmc_result release function using free() for releasing the memory.

This function is used in the evmc_make_result(), but may be also used in other case if convenient.

Parameters
resultThe result object.

Definition at line 109 of file helpers.h.

110{
111 free((uint8_t*)result->output_data);
112}
const uint8_t * output_data
The reference to output data.
Definition: evmc.h:448

◆ evmc_is_abi_compatible()

static bool evmc_is_abi_compatible ( struct evmc_vm vm)
inlinestatic

Returns true if the VM has a compatible ABI version.

Definition at line 32 of file helpers.h.

33{
34 return vm->abi_version == EVMC_ABI_VERSION;
35}
@ EVMC_ABI_VERSION
The EVMC ABI version number of the interface declared in this file.
Definition: evmc.h:47
const int abi_version
EVMC ABI version implemented by the VM instance.
Definition: evmc.h:1147

◆ evmc_make_result()

static struct evmc_result evmc_make_result ( enum evmc_status_code  status_code,
int64_t  gas_left,
int64_t  gas_refund,
const uint8_t *  output_data,
size_t  output_size 
)
inlinestatic

Creates the result from the provided arguments.

The provided output is copied to memory allocated with malloc() and the evmc_result::release function is set to one invoking free().

In case of memory allocation failure, the result has all fields zeroed and only evmc_result::status_code is set to EVMC_OUT_OF_MEMORY internal error.

Parameters
status_codeThe status code.
gas_leftThe amount of gas left.
gas_refundThe amount of refunded gas.
output_dataThe pointer to the output.
output_sizeThe output size.

Definition at line 127 of file helpers.h.

132{
133 struct evmc_result result;
134 memset(&result, 0, sizeof(result));
135
136 if (output_size != 0)
137 {
138 uint8_t* buffer = (uint8_t*)malloc(output_size);
139
140 if (!buffer)
141 {
142 result.status_code = EVMC_OUT_OF_MEMORY;
143 return result;
144 }
145
146 memcpy(buffer, output_data, output_size);
147 result.output_data = buffer;
148 result.output_size = output_size;
149 result.release = evmc_free_result_memory;
150 }
151
152 result.status_code = status_code;
153 result.gas_left = gas_left;
154 result.gas_refund = gas_refund;
155 return result;
156}
@ EVMC_OUT_OF_MEMORY
The VM failed to allocate the amount of memory needed for execution.
Definition: evmc.h:390
static void evmc_free_result_memory(const struct evmc_result *result)
The evmc_result release function using free() for releasing the memory.
Definition: helpers.h:109
The EVM code execution result.
Definition: evmc.h:416
enum evmc_status_code status_code
The execution status code.
Definition: evmc.h:418
int64_t gas_refund
The refunded gas accumulated from this execution and its sub-calls.
Definition: evmc.h:434
size_t output_size
The size of the output data.
Definition: evmc.h:455
int64_t gas_left
The amount of gas left after the execution.
Definition: evmc.h:426

◆ evmc_release_result()

static void evmc_release_result ( struct evmc_result result)
inlinestatic

Releases the resources allocated to the execution result.

Parameters
resultThe result object to be released. MUST NOT be NULL.
See also
evmc_result::release() evmc_release_result_fn

Definition at line 165 of file helpers.h.

166{
167 if (result->release)
168 result->release(result);
169}
evmc_release_result_fn release
The method releasing all resources associated with the result object.
Definition: evmc.h:476

◆ evmc_revision_to_string()

static const char * evmc_revision_to_string ( enum evmc_revision  rev)
inlinestatic

Returns the name of the evmc_revision.

Definition at line 272 of file helpers.h.

273{
274 switch (rev)
275 {
276 case EVMC_FRONTIER:
277 return "Frontier";
278 case EVMC_HOMESTEAD:
279 return "Homestead";
281 return "Tangerine Whistle";
283 return "Spurious Dragon";
284 case EVMC_BYZANTIUM:
285 return "Byzantium";
287 return "Constantinople";
288 case EVMC_PETERSBURG:
289 return "Petersburg";
290 case EVMC_ISTANBUL:
291 return "Istanbul";
292 case EVMC_BERLIN:
293 return "Berlin";
294 case EVMC_LONDON:
295 return "London";
296 case EVMC_PARIS:
297 return "Paris";
298 case EVMC_SHANGHAI:
299 return "Shanghai";
300 case EVMC_CANCUN:
301 return "Cancun";
302 case EVMC_PRAGUE:
303 return "Prague";
304 case EVMC_OSAKA:
305 return "Osaka";
306 }
307 return "<unknown>";
308}
@ EVMC_OSAKA
The Osaka revision.
Definition: evmc.h:1047
@ EVMC_HOMESTEAD
The Homestead revision.
Definition: evmc.h:954
@ EVMC_PRAGUE
The Prague revision.
Definition: evmc.h:1040
@ EVMC_ISTANBUL
The Istanbul revision.
Definition: evmc.h:998
@ EVMC_FRONTIER
The Frontier revision.
Definition: evmc.h:947
@ EVMC_PETERSBURG
The Petersburg revision.
Definition: evmc.h:991
@ EVMC_CONSTANTINOPLE
The Constantinople revision.
Definition: evmc.h:982
@ EVMC_TANGERINE_WHISTLE
The Tangerine Whistle revision.
Definition: evmc.h:961
@ EVMC_SPURIOUS_DRAGON
The Spurious Dragon revision.
Definition: evmc.h:968
@ EVMC_BYZANTIUM
The Byzantium revision.
Definition: evmc.h:975
@ EVMC_CANCUN
The Cancun revision.
Definition: evmc.h:1033
@ EVMC_SHANGHAI
The Shanghai revision.
Definition: evmc.h:1026
@ EVMC_LONDON
The London revision.
Definition: evmc.h:1012
@ EVMC_PARIS
The Paris revision (aka The Merge).
Definition: evmc.h:1019
@ EVMC_BERLIN
The Berlin revision.
Definition: evmc.h:1005

◆ evmc_set_option()

static enum evmc_set_option_result evmc_set_option ( struct evmc_vm vm,
char const *  name,
char const *  value 
)
inlinestatic

Sets the option for the VM, if the feature is supported by the VM.

See also
evmc_set_option_fn

Definition at line 78 of file helpers.h.

81{
82 if (vm->set_option)
83 return vm->set_option(vm, name, value);
84 return EVMC_SET_OPTION_INVALID_NAME;
85}
evmc_set_option_fn set_option
Optional pointer to function modifying VM's options.
Definition: evmc.h:1196

◆ evmc_status_code_to_string()

static const char * evmc_status_code_to_string ( enum evmc_status_code  status_code)
inlinestatic

Returns text representation of the evmc_status_code.

Definition at line 221 of file helpers.h.

222{
223 switch (status_code)
224 {
225 case EVMC_SUCCESS:
226 return "success";
227 case EVMC_FAILURE:
228 return "failure";
229 case EVMC_REVERT:
230 return "revert";
231 case EVMC_OUT_OF_GAS:
232 return "out of gas";
234 return "invalid instruction";
236 return "undefined instruction";
238 return "stack overflow";
240 return "stack underflow";
242 return "bad jump destination";
244 return "invalid memory access";
246 return "call depth exceeded";
248 return "static mode violation";
250 return "precompile failure";
252 return "contract validation failure";
254 return "argument out of range";
256 return "wasm unreachable instruction";
257 case EVMC_WASM_TRAP:
258 return "wasm trap";
260 return "insufficient balance";
262 return "internal error";
263 case EVMC_REJECTED:
264 return "rejected";
266 return "out of memory";
267 }
268 return "<unknown>";
269}
@ EVMC_INSUFFICIENT_BALANCE
The caller does not have enough funds for value transfer.
Definition: evmc.h:371
@ EVMC_ARGUMENT_OUT_OF_RANGE
An argument to a state accessing method has a value outside of the accepted range of values.
Definition: evmc.h:357
@ EVMC_INVALID_MEMORY_ACCESS
Tried to read outside memory bounds.
Definition: evmc.h:332
@ EVMC_REJECTED
The execution of the given code and/or message has been rejected by the EVM implementation.
Definition: evmc.h:387
@ EVMC_UNDEFINED_INSTRUCTION
An undefined instruction has been encountered.
Definition: evmc.h:313
@ EVMC_SUCCESS
Execution finished with success.
Definition: evmc.h:286
@ EVMC_STACK_UNDERFLOW
Execution of an opcode has required more items on the EVM stack.
Definition: evmc.h:322
@ EVMC_BAD_JUMP_DESTINATION
Execution has violated the jump destination restrictions.
Definition: evmc.h:325
@ EVMC_INVALID_INSTRUCTION
The designated INVALID instruction has been hit during execution.
Definition: evmc.h:310
@ EVMC_STATIC_MODE_VIOLATION
Tried to execute an operation which is restricted in static mode.
Definition: evmc.h:338
@ EVMC_WASM_TRAP
A WebAssembly trap has been hit during execution.
Definition: evmc.h:368
@ EVMC_PRECOMPILE_FAILURE
A call to a precompiled or system contract has ended with a failure.
Definition: evmc.h:345
@ EVMC_INTERNAL_ERROR
EVM implementation generic internal error.
Definition: evmc.h:374
@ EVMC_OUT_OF_GAS
The execution has run out of gas.
Definition: evmc.h:300
@ EVMC_CONTRACT_VALIDATION_FAILURE
Contract validation has failed (e.g.
Definition: evmc.h:351
@ EVMC_CALL_DEPTH_EXCEEDED
Call depth has exceeded the limit (if any)
Definition: evmc.h:335
@ EVMC_WASM_UNREACHABLE_INSTRUCTION
A WebAssembly unreachable instruction has been hit during execution.
Definition: evmc.h:362
@ EVMC_STACK_OVERFLOW
The execution has attempted to put more items on the EVM stack than the specified limit.
Definition: evmc.h:319
@ EVMC_FAILURE
Generic execution failure.
Definition: evmc.h:289
@ EVMC_REVERT
Execution terminated with REVERT opcode.
Definition: evmc.h:297

◆ evmc_vm_has_capability()

static bool evmc_vm_has_capability ( struct evmc_vm vm,
enum evmc_capabilities  capability 
)
inlinestatic

Checks if the VM has the given capability.

See also
evmc_get_capabilities_fn

Definition at line 58 of file helpers.h.

59{
60 return (vm->get_capabilities(vm) & (evmc_capabilities_flagset)capability) != 0;
61}
uint32_t evmc_capabilities_flagset
Alias for unsigned integer representing a set of bit flags of EVMC capabilities.
Definition: evmc.h:1120
evmc_get_capabilities_fn get_capabilities
A method returning capabilities supported by the VM instance.
Definition: evmc.h:1189

◆ evmc_vm_name()

static const char * evmc_vm_name ( struct evmc_vm vm)
inlinestatic

Returns the name of the VM.

Definition at line 40 of file helpers.h.

41{
42 return vm->name;
43}
const char * name
The name of the EVMC VM implementation.
Definition: evmc.h:1155

◆ evmc_vm_version()

static const char * evmc_vm_version ( struct evmc_vm vm)
inlinestatic

Returns the version of the VM.

Definition at line 48 of file helpers.h.

49{
50 return vm->version;
51}
const char * version
The version of the EVMC VM implementation, e.g.
Definition: evmc.h:1163