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_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.
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.
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

enum 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.

{
    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
};

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

filename	The 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_code	The 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:

• EVMC_LOADER_INVALID_OPTION_NAME when the provided options list contains an option unknown for the VM,
• EVMC_LOADER_INVALID_OPTION_VALUE when there exists unsupported value for a given VM option.

Parameters

config	The path to the EVMC module with additional configuration options.
error_code	The 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:

• EVMC_LOADER_VM_CREATION_FAILURE when the create function returns NULL,
• EVMC_LOADER_ABI_VERSION_MISMATCH when the created VM instance has ABI version different from the ABI version of this library (EVMC_ABI_VERSION).

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

filename	The 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_code	The 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.