Rename evmc_instance -> evmc_vm

CHANGELOG.md

@@ -18,6 +18,8 @@ and this project adheres to [Semantic Versioning].
 
 ### Changed
 
+- The `evmc_instance` renamed to `evmc_vm`.
+  [[#430](https://github.com/ethereum/evmc/pull/430)]
 - The `evmc::vm` renamed to `evmc::VM` in C++ API.
   [[#252](https://github.com/ethereum/evmc/pull/252)]
 - Previously deprecated `helpers.hpp` header file has been removed.

bindings/go/evmc/evmc.go

@@ -15,9 +15,9 @@ package evmc
 #include <stdlib.h>
 #include <string.h>
 
-static inline enum evmc_set_option_result set_option(struct evmc_instance* instance, char* name, char* value)
+static inline enum evmc_set_option_result set_option(struct evmc_vm* vm, char* name, char* value)
 {
-	enum evmc_set_option_result ret = evmc_set_option(instance, name, value);
+	enum evmc_set_option_result ret = evmc_set_option(vm, name, value);
 	free(name);
 	free(value);
 	return ret;
@@ -31,7 +31,7 @@ struct extended_context
 
 extern const struct evmc_host_interface evmc_go_host;
 
-static struct evmc_result execute_wrapper(struct evmc_instance* instance,
+static struct evmc_result execute_wrapper(struct evmc_vm* vm,
 	int64_t context_index, enum evmc_revision rev,
 	enum evmc_call_kind kind, uint32_t flags, int32_t depth, int64_t gas,
 	const evmc_address* destination, const evmc_address* sender,
@@ -52,7 +52,7 @@ static struct evmc_result execute_wrapper(struct evmc_instance* instance,
 	};
 
 	struct extended_context ctx = {{&evmc_go_host}, context_index};
-	return evmc_execute(instance, &ctx.context, rev, &msg, code, code_size);
+	return evmc_execute(vm, &ctx.context, rev, &msg, code, code_size);
 }
 */
 import "C"
@@ -144,18 +144,18 @@ const (
 	Istanbul         Revision = C.EVMC_ISTANBUL
 )
 
-type Instance struct {
-	handle *C.struct_evmc_instance
+type VM struct {
+	handle *C.struct_evmc_vm
 }
 
-func Load(filename string) (instance *Instance, err error) {
+func Load(filename string) (vm *VM, err error) {
 	cfilename := C.CString(filename)
 	var loaderErr C.enum_evmc_loader_error_code
 	handle := C.evmc_load_and_create(cfilename, &loaderErr)
 	C.free(unsafe.Pointer(cfilename))
 
 	if loaderErr == C.EVMC_LOADER_SUCCESS {
-		instance = &Instance{handle}
+		vm = &VM{handle}
 	} else {
 		errMsg := C.evmc_last_error_msg()
 		if errMsg != nil {
@@ -165,17 +165,17 @@ func Load(filename string) (instance *Instance, err error) {
 		}
 	}
 
-	return instance, err
+	return vm, err
 }
 
-func LoadAndConfigure(config string) (instance *Instance, err error) {
+func LoadAndConfigure(config string) (vm *VM, err error) {
 	cconfig := C.CString(config)
 	var loaderErr C.enum_evmc_loader_error_code
 	handle := C.evmc_load_and_configure(cconfig, &loaderErr)
 	C.free(unsafe.Pointer(cconfig))
 
 	if loaderErr == C.EVMC_LOADER_SUCCESS {
-		instance = &Instance{handle}
+		vm = &VM{handle}
 	} else {
 		errMsg := C.evmc_last_error_msg()
 		if errMsg != nil {
@@ -185,21 +185,21 @@ func LoadAndConfigure(config string) (instance *Instance, err error) {
 		}
 	}
 
-	return instance, err
+	return vm, err
 }
 
-func (instance *Instance) Destroy() {
-	C.evmc_destroy(instance.handle)
+func (vm *VM) Destroy() {
+	C.evmc_destroy(vm.handle)
 }
 
-func (instance *Instance) Name() string {
-	// TODO: consider using C.evmc_vm_name(instance.handle)
-	return C.GoString(instance.handle.name)
+func (vm *VM) Name() string {
+	// TODO: consider using C.evmc_vm_name(vm.handle)
+	return C.GoString(vm.handle.name)
 }
 
-func (instance *Instance) Version() string {
-	// TODO: consider using C.evmc_vm_version(instance.handle)
-	return C.GoString(instance.handle.version)
+func (vm *VM) Version() string {
+	// TODO: consider using C.evmc_vm_version(vm.handle)
+	return C.GoString(vm.handle.version)
 }
 
 type Capability uint32
@@ -209,13 +209,13 @@ const (
 	CapabilityEWASM Capability = C.EVMC_CAPABILITY_EWASM
 )
 
-func (instance *Instance) HasCapability(capability Capability) bool {
-	return bool(C.evmc_vm_has_capability(instance.handle, uint32(capability)))
+func (vm *VM) HasCapability(capability Capability) bool {
+	return bool(C.evmc_vm_has_capability(vm.handle, uint32(capability)))
 }
 
-func (instance *Instance) SetOption(name string, value string) (err error) {
+func (vm *VM) SetOption(name string, value string) (err error) {
 
-	r := C.set_option(instance.handle, C.CString(name), C.CString(value))
+	r := C.set_option(vm.handle, C.CString(name), C.CString(value))
 	switch r {
 	case C.EVMC_SET_OPTION_INVALID_NAME:
 		err = fmt.Errorf("evmc: option '%s' not accepted", name)
@@ -226,7 +226,7 @@ func (instance *Instance) SetOption(name string, value string) (err error) {
 	return err
 }
 
-func (instance *Instance) Execute(ctx HostContext, rev Revision,
+func (vm *VM) Execute(ctx HostContext, rev Revision,
 	kind CallKind, static bool, depth int, gas int64,
 	destination common.Address, sender common.Address, input []byte, value common.Hash,
 	code []byte, create2Salt common.Hash) (output []byte, gasLeft int64, err error) {
@@ -242,7 +242,7 @@ func (instance *Instance) Execute(ctx HostContext, rev Revision,
 	evmcSender := evmcAddress(sender)
 	evmcValue := evmcBytes32(value)
 	evmcCreate2Salt := evmcBytes32(create2Salt)
-	result := C.execute_wrapper(instance.handle, C.int64_t(ctxId), uint32(rev),
+	result := C.execute_wrapper(vm.handle, C.int64_t(ctxId), uint32(rev),
 		C.enum_evmc_call_kind(kind), flags, C.int32_t(depth), C.int64_t(gas),
 		&evmcDestination, &evmcSender, bytesPtr(input), C.size_t(len(input)), &evmcValue,
 		bytesPtr(code), C.size_t(len(code)), &evmcCreate2Salt)

bindings/rust/evmc-declare/src/lib.rs

@@ -272,7 +272,7 @@ fn build_capabilities_fn(capabilities: u32) -> proc_macro2::TokenStream {
         LitInt::new(capabilities as u64, IntSuffix::U32, capabilities.span());
 
     quote! {
-        extern "C" fn __evmc_get_capabilities(instance: *mut ::evmc_vm::ffi::evmc_instance) -> ::evmc_vm::ffi::evmc_capabilities_flagset {
+        extern "C" fn __evmc_get_capabilities(instance: *mut ::evmc_vm::ffi::evmc_vm) -> ::evmc_vm::ffi::evmc_capabilities_flagset {
             #capabilities_literal
         }
     }
@@ -289,8 +289,8 @@ fn build_create_fn(names: &VMNameSet) -> proc_macro2::TokenStream {
     // Note: we can get CStrs unchecked because we did the checks on instantiation of VMMetaData.
     quote! {
         #[no_mangle]
-        extern "C" fn #fn_ident() -> *const ::evmc_vm::ffi::evmc_instance {
-            let new_instance = ::evmc_vm::ffi::evmc_instance {
+        extern "C" fn #fn_ident() -> *const ::evmc_vm::ffi::evmc_vm {
+            let new_instance = ::evmc_vm::ffi::evmc_vm {
                 abi_version: ::evmc_vm::ffi::EVMC_ABI_VERSION as i32,
                 destroy: Some(__evmc_destroy),
                 execute: Some(__evmc_execute),
@@ -315,7 +315,7 @@ fn build_destroy_fn(names: &VMNameSet) -> proc_macro2::TokenStream {
     let type_ident = names.get_type_as_ident();
 
     quote! {
-        extern "C" fn __evmc_destroy(instance: *mut ::evmc_vm::ffi::evmc_instance) {
+        extern "C" fn __evmc_destroy(instance: *mut ::evmc_vm::ffi::evmc_vm) {
             if instance.is_null() {
                 // This is an irrecoverable error that violates the EVMC spec.
                 std::process::abort();
@@ -334,7 +334,7 @@ fn build_execute_fn(names: &VMNameSet) -> proc_macro2::TokenStream {
 
     quote! {
         extern "C" fn __evmc_execute(
-            instance: *mut ::evmc_vm::ffi::evmc_instance,
+            instance: *mut ::evmc_vm::ffi::evmc_vm,
             context: *mut ::evmc_vm::ffi::evmc_host_context,
             revision: ::evmc_vm::ffi::evmc_revision,
             msg: *const ::evmc_vm::ffi::evmc_message,

bindings/rust/evmc-vm/src/container.rs

@@ -13,7 +13,7 @@ where
     T: EvmcVm + Sized,
 {
     #[allow(dead_code)]
-    instance: ::evmc_sys::evmc_instance,
+    instance: ::evmc_sys::evmc_vm,
     vm: T,
 }
 
@@ -22,22 +22,22 @@ where
     T: EvmcVm + Sized,
 {
     /// Basic constructor.
-    pub fn new(_instance: ::evmc_sys::evmc_instance) -> Box<Self> {
+    pub fn new(_instance: ::evmc_sys::evmc_vm) -> Box<Self> {
         Box::new(Self {
             instance: _instance,
             vm: T::init(),
         })
     }
 
     /// Take ownership of the given pointer and return a box.
-    pub unsafe fn from_ffi_pointer(instance: *mut ::evmc_sys::evmc_instance) -> Box<Self> {
+    pub unsafe fn from_ffi_pointer(instance: *mut ::evmc_sys::evmc_vm) -> Box<Self> {
         assert!(!instance.is_null(), "from_ffi_pointer received NULL");
         Box::from_raw(instance as *mut EvmcContainer<T>)
     }
 
     /// Convert boxed self into an FFI pointer, surrendering ownership of the heap data.
-    pub unsafe fn into_ffi_pointer(boxed: Box<Self>) -> *mut ::evmc_sys::evmc_instance {
-        Box::into_raw(boxed) as *mut ::evmc_sys::evmc_instance
+    pub unsafe fn into_ffi_pointer(boxed: Box<Self>) -> *mut ::evmc_sys::evmc_vm {
+        Box::into_raw(boxed) as *mut ::evmc_sys::evmc_vm
     }
 }
 
@@ -91,7 +91,7 @@ mod tests {
 
     #[test]
     fn container_new() {
-        let instance = ::evmc_sys::evmc_instance {
+        let instance = ::evmc_sys::evmc_vm {
             abi_version: ::evmc_sys::EVMC_ABI_VERSION as i32,
             name: std::ptr::null(),
             version: std::ptr::null(),

docs/Host_Guide.md

@@ -21,17 +21,17 @@ When Host implementation is ready it's time to start using EVMC VMs.
 1. Firstly, create a VM instance. You need to know what is the name of the "create"
    function in particular VM implementation. The EVMC recommends to name the 
    function by the VM codename, e.g. ::evmc_create_example_vm().
-   Invoking the create function will give you the VM instance (::evmc_instance). 
+   Invoking the create function will give you the VM instance (::evmc_vm). 
    It is recommended to create the VM instance once.
 
 2. If you are interested in loading VMs dynamically (i.e. to use DLLs) 
    check out the [EVMC Loader](@ref loader) library.
 
-3. The ::evmc_instance contains information about the VM like 
-   name (::evmc_instance::name) or ABI version (::evmc_instance::abi_version)
+3. The ::evmc_vm contains information about the VM like 
+   name (::evmc_vm::name) or ABI version (::evmc_vm::abi_version)
    and methods.
 
-4. To execute code in the VM use the "execute()" method (::evmc_instance::execute).
+4. To execute code in the VM use the "execute()" method (::evmc_vm::execute).
    You will need:
    - the code to execute,
    - the message (::evmc_message) object that describes the execution context,

docs/VM_Guide.md

@@ -8,7 +8,7 @@ You can start with [the example implementation of EVMC VM interface in C](@ref e
 
 ## VM instance
 
-The VM instance is described by the ::evmc_instance struct. It contains the
+The VM instance is described by the ::evmc_vm struct. It contains the
 basic static information about the VM like name and version. The struct also
 includes the VM methods (in form of function pointers) to allow the Host
 to interact with the VM.
@@ -25,17 +25,17 @@ e.g. ::evmc_create_example_vm().
 
 ## VM methods implementation
 
-Each VM methods takes the pointer to the ::evmc_instance as the first argument.
-The VM implementation can extend the ::evmc_instance struct for storing internal
+Each VM methods takes the pointer to the ::evmc_vm as the first argument.
+The VM implementation can extend the ::evmc_vm struct for storing internal
 data. This allow implementing the VM in object-oriented manner.
 
-The most important method is ::evmc_instance::execute() because it executes EVM code.
+The most important method is ::evmc_vm::execute() because it executes EVM code.
 Remember that the Host is allowed to invoke the execute method concurrently
 so do not store data related to a particular execution context in the VM instance.
 
 Before a client can actually execute a VM, it is important to implement the three
-basic fields for querying name (::evmc_instance::name), version (::evmc_instance::version)
-and capabilities (::evmc_instance::get_capabilities()) as well as the ::evmc_instance::destroy()
+basic fields for querying name (::evmc_vm::name), version (::evmc_vm::version)
+and capabilities (::evmc_vm::get_capabilities()) as well as the ::evmc_vm::destroy()
 method to wind the VM down.
 
 Other methods are optional.

examples/example.c

@@ -19,15 +19,15 @@ int main(int argc, char* argv[])
 #ifdef STATICALLY_LINKED_EXAMPLE
     (void)argc;
     (void)argv;
-    struct evmc_instance* vm = evmc_create_example_vm();
+    struct evmc_vm* vm = evmc_create_example_vm();
     if (!vm)
-        return EVMC_LOADER_INSTANCE_CREATION_FAILURE;
+        return EVMC_LOADER_VM_CREATION_FAILURE;
     if (!evmc_is_abi_compatible(vm))
         return EVMC_LOADER_ABI_VERSION_MISMATCH;
 #else
     const char* config_string = (argc > 1) ? argv[1] : "example-vm.so";
     enum evmc_loader_error_code error_code;
-    struct evmc_instance* vm = evmc_load_and_configure(config_string, &error_code);
+    struct evmc_vm* vm = evmc_load_and_configure(config_string, &error_code);
     if (!vm)
     {
         printf("Loading error: %d\n", error_code);

examples/example_precompiles_vm/example_precompiles_vm.cpp

@@ -48,7 +48,7 @@ static evmc_result not_implemented()
     return result;
 }
 
-static evmc_result execute(evmc_instance*,
+static evmc_result execute(evmc_vm*,
                            evmc_host_context*,
                            enum evmc_revision rev,
                            const evmc_message* msg,
@@ -111,16 +111,16 @@ static evmc_result execute(evmc_instance*,
     }
 }
 
-extern "C" EVMC_EXPORT evmc_instance* evmc_create_example_precompiles_vm()
+extern "C" EVMC_EXPORT evmc_vm* evmc_create_example_precompiles_vm()
 {
-    static struct evmc_instance instance = {
+    static struct evmc_vm vm = {
         EVMC_ABI_VERSION,
         "example_precompiles_vm",
         PROJECT_VERSION,
-        [](evmc_instance*) {},
+        [](evmc_vm*) {},
         execute,
-        [](evmc_instance*) { return evmc_capabilities_flagset{EVMC_CAPABILITY_PRECOMPILES}; },
+        [](evmc_vm*) { return evmc_capabilities_flagset{EVMC_CAPABILITY_PRECOMPILES}; },
         nullptr,
     };
-    return &instance;
+    return &vm;
 }