EVMC
EVMC Loader

EVMC Loader Library. More...

Typedefs

typedef struct evmc_vm *(* evmc_create_fn) (void)
 The function pointer type for EVMC create functions.
 

Enumerations

enum  evmc_loader_error_code {
  EVMC_LOADER_SUCCESS = 0 , EVMC_LOADER_CANNOT_OPEN = 1 , EVMC_LOADER_SYMBOL_NOT_FOUND = 2 , EVMC_LOADER_INVALID_ARGUMENT = 3 ,
  EVMC_LOADER_VM_CREATION_FAILURE = 4 , EVMC_LOADER_ABI_VERSION_MISMATCH = 5 , EVMC_LOADER_INVALID_OPTION_NAME = 6 , EVMC_LOADER_INVALID_OPTION_VALUE = 7 ,
  EVMC_LOADER_UNSPECIFIED_ERROR = -1
}
 Error codes for the EVMC loader. More...
 

Functions

evmc_create_fn evmc_load (const char *filename, enum evmc_loader_error_code *error_code)
 Dynamically loads the EVMC module with a VM implementation.
 
struct evmc_vmevmc_load_and_create (const char *filename, enum evmc_loader_error_code *error_code)
 Dynamically loads the EVMC module and creates the VM instance.
 
struct evmc_vmevmc_load_and_configure (const char *config, enum evmc_loader_error_code *error_code)
 Dynamically loads the EVMC module, then creates and configures the VM instance.
 
const char * evmc_last_error_msg (void)
 Returns the human-readable message describing the most recent error that occurred in EVMC loading since the last call to this function.
 

Detailed Description

EVMC Loader Library.

The EVMC Loader Library supports loading VMs implemented as Dynamically Loaded Libraries (DLLs, shared objects).

Typedef Documentation

◆ evmc_create_fn

typedef struct evmc_vm *(* evmc_create_fn) (void)

The function pointer type for EVMC create functions.

Definition at line 1 of file loader.h.

Enumeration Type Documentation

◆ evmc_loader_error_code

Error codes for the EVMC loader.

Objects of this type SHOULD be initialized with EVMC_LOADER_UNSPECIFIED_ERROR before passing to the EVMC loader.

Enumerator
EVMC_LOADER_SUCCESS 

The loader succeeded.

EVMC_LOADER_CANNOT_OPEN 

The loader cannot open the given file name.

EVMC_LOADER_SYMBOL_NOT_FOUND 

The VM create function not found.

EVMC_LOADER_INVALID_ARGUMENT 

The invalid argument value provided.

EVMC_LOADER_VM_CREATION_FAILURE 

The creation of a VM instance has failed.

EVMC_LOADER_ABI_VERSION_MISMATCH 

The ABI version of the VM instance has mismatched.

EVMC_LOADER_INVALID_OPTION_NAME 

The VM option is invalid.

EVMC_LOADER_INVALID_OPTION_VALUE 

The VM option value is invalid.

EVMC_LOADER_UNSPECIFIED_ERROR 

This error value will be never returned by the EVMC loader, but can be used by users to init evmc_loader_error_code objects.

Definition at line 27 of file loader.h.

28{
31
34
37
40
43
46
49
52
56};
@ EVMC_LOADER_SUCCESS
The loader succeeded.
Definition: loader.h:30
@ EVMC_LOADER_ABI_VERSION_MISMATCH
The ABI version of the VM instance has mismatched.
Definition: loader.h:45
@ EVMC_LOADER_CANNOT_OPEN
The loader cannot open the given file name.
Definition: loader.h:33
@ EVMC_LOADER_UNSPECIFIED_ERROR
This error value will be never returned by the EVMC loader, but can be used by users to init evmc_loa...
Definition: loader.h:55
@ EVMC_LOADER_INVALID_ARGUMENT
The invalid argument value provided.
Definition: loader.h:39
@ EVMC_LOADER_SYMBOL_NOT_FOUND
The VM create function not found.
Definition: loader.h:36
@ EVMC_LOADER_VM_CREATION_FAILURE
The creation of a VM instance has failed.
Definition: loader.h:42
@ EVMC_LOADER_INVALID_OPTION_NAME
The VM option is invalid.
Definition: loader.h:48
@ EVMC_LOADER_INVALID_OPTION_VALUE
The VM option value is invalid.
Definition: loader.h:51

Function Documentation

◆ evmc_last_error_msg()

const char * evmc_last_error_msg ( void  )

Returns the human-readable message describing the most recent error that occurred in EVMC loading since the last call to this function.

In case any loading function returned EVMC_LOADER_SUCCESS this function always returns NULL. In case of error code other than success returned, this function MAY return the error message. Calling this function "consumes" the error message and the function will return NULL from subsequent invocations. This function is not thread-safe.

Returns
Error message or NULL if no additional information is available. The returned pointer MUST NOT be freed by the caller.

◆ evmc_load()

evmc_create_fn evmc_load ( const char *  filename,
enum evmc_loader_error_code error_code 
)

Dynamically loads the EVMC module with a VM implementation.

This function tries to open a dynamically loaded library (DLL) at the given filename. On UNIX-like systems dlopen() function is used. On Windows LoadLibrary() function is used.

If the file does not exist or is not a valid shared library the EVMC_LOADER_CANNOT_OPEN error code is signaled and NULL is returned.

After the DLL is successfully loaded the function tries to find the EVM create function in the library. The filename is used to guess the EVM name and the name of the create function. The create function name is constructed by the following rules. Consider example path: "/ethereum/libexample-interpreter.so.1.0".

  • the filename is taken from the path: "libexample-interpreter.so.1.0",
  • the "lib" prefix and all file extensions are stripped from the name: "example-interpreter"
  • all "-" are replaced with "_" to construct base name: "example_interpreter",
  • the function name "evmc_create_" + base name is searched in the library: "evmc_create_example_interpreter",
  • if the function is not found, the function name "evmc_create" is searched in the library.

If the create function is found in the library, the pointer to the function is returned. Otherwise, the EVMC_LOADER_SYMBOL_NOT_FOUND error code is signaled and NULL is returned.

It is safe to call this function with the same filename argument multiple times (the DLL is not going to be loaded multiple times).

Parameters
filenameThe null terminated path (absolute or relative) to an EVMC module (dynamically loaded library) containing the VM implementation. If the value is NULL, an empty C-string or longer than the path maximum length the EVMC_LOADER_INVALID_ARGUMENT is signaled.
error_codeThe pointer to the error code. If not NULL the value is set to EVMC_LOADER_SUCCESS on success or any other error code as described above.
Returns
The pointer to the EVM create function or NULL in case of error.

◆ evmc_load_and_configure()

struct evmc_vm * evmc_load_and_configure ( const char *  config,
enum evmc_loader_error_code error_code 
)

Dynamically loads the EVMC module, then creates and configures the VM instance.

This function performs the following actions atomically:

  • loads the EVMC module (as evmc_load()),
  • creates the VM instance,
  • configures the VM instance with options provided in the config parameter.

The configuration string (config) has the following syntax:

<path> ("," <option-name> ["=" <option-value>])*

In this syntax, an option without a value can be specified (,option,) as a shortcut for using empty value (,option=,).

Options are passed to a VM in the order they are specified in the configuration string. It is up to the VM implementation how to handle duplicated options and other conflicts.

Example configuration string:

./modules/vm.so,engine=compiler,trace,verbosity=2

The function signals the same errors as evmc_load_and_create() and additionally:

Parameters
configThe path to the EVMC module with additional configuration options.
error_codeThe pointer to the error code. If not NULL the value is set to EVMC_LOADER_SUCCESS on success or any other error code as described above.
Returns
The pointer to the created VM or NULL in case of error.

◆ evmc_load_and_create()

struct evmc_vm * evmc_load_and_create ( const char *  filename,
enum evmc_loader_error_code error_code 
)

Dynamically loads the EVMC module and creates the VM instance.

This is a macro for creating the VM instance with the function returned from evmc_load(). The function signals the same errors as evmc_load() and additionally:

It is safe to call this function with the same filename argument multiple times: the DLL is not going to be loaded multiple times, but the function will return new VM instance each time.

Parameters
filenameThe null terminated path (absolute or relative) to an EVMC module (dynamically loaded library) containing the VM implementation. If the value is NULL, an empty C-string or longer than the path maximum length the EVMC_LOADER_INVALID_ARGUMENT is signaled.
error_codeThe pointer to the error code. If not NULL the value is set to EVMC_LOADER_SUCCESS on success or any other error code as described above.
Returns
The pointer to the created VM or NULL in case of error.