docs: VM Implementation Guide

docs/EVMC.md

@@ -2,13 +2,14 @@
 
 The EVMC is the low-level ABI between Ethereum Virtual Machines (EVMs) and
 Ethereum Clients. On the EVM-side it supports classic EVM1 and [eWASM].
-On the Client-side it defines the interface for EVM implementations 
+On the Client-side it defines the interface for EVM implementations
 to access Ethereum environment and state.
 
 
 # Guides
 
 - [Host Implementation Guide](@ref hostguide)
+- [VM Implementation Guide](@ref vmguide)
 
 
 # Versioning {#versioning}
@@ -22,13 +23,13 @@ can be referenced as EVMC ABIv3 or just EVMC 3.
 
 # Modules
 
-- [EVMC](@ref EVMC) 
+- [EVMC](@ref EVMC)
    – the main component that defines API for VMs and Clients (Hosts).
 - [EVMC Loader](@ref loader)
-   – the library for loading VMs implemented as Dynamically Loaded Libraries (DLLs, shared objects). 
+   – the library for loading VMs implemented as Dynamically Loaded Libraries (DLLs, shared objects).
 - [EVMC Helpers](@ref helpers)
    – a collection of utility functions for easier integration with EVMC.
-- [EVM Instructions](@ref instructions) 
+- [EVM Instructions](@ref instructions)
    – the library with collection of metrics for EVM1 instruction set.
 - [EVMC VM Tester](@ref vmtester)
    – the EVMC-compatibility testing tool for VM implementations.
@@ -42,10 +43,10 @@ can be referenced as EVMC ABIv3 or just EVMC 3.
 ## Terms
 
 1. **VM** – An Ethereum Virtual Machine instance/implementation.
-2. **Host** – An entity controlling the VM. 
-   The Host requests code execution and responses to VM queries by callback 
+2. **Host** – An entity controlling the VM.
+   The Host requests code execution and responses to VM queries by callback
    functions. This usually represents an Ethereum Client.
-   
+
 
 ## Responsibilities
 
@@ -56,8 +57,8 @@ can be referenced as EVMC ABIv3 or just EVMC 3.
   counter.
 - Controls the call depth, including the exceptional termination of execution
   in case the maximum depth is reached.
-  
-  
+
+
 ### Host
 
 - Provides access to State.

docs/VM_Guide.md

@@ -0,0 +1,46 @@
+# EVMC VM Implementation Guide {#vmguide}
+
+> How to add EVMC interface to Your Ethereum VM implementation.
+
+## An example
+
+You can start with [the example implementation of EVMC VM interface in C](../examples/example_vm.c).
+
+## VM instance
+
+The VM instance is described by the ::evmc_instance 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.
+
+Some methods are optional. The VM must implement at least all mandatory ones.
+
+The instance struct must also include the EVMC ABI version (::EVMC_ABI_VERSION)
+it was build with. This allows the Host to check the ABI compatibility when
+loading VMs dynamically.
+
+The VM instance is created and returned as a pointer from a special "create"
+function. The EVMC recommends to name the function by the VM codename,
+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
+data. This allow implementing the VM in object-oriented manner.
+
+The most important method is ::evmc_execute_fn() 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.
+
+## Resource management
+
+All additional resources allocated when the VM instance is created must be
+freed when the destroy method is invoked.
+
+The VM implementation can also attach additional resources to the ::evmc_result
+of an execution. These resource must be freed when the ::evmc_result::release
+method is invoked.
+
+
+*Have fun!*