From 086e5861213ffaa6b4da028bbbc32876dc930400 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Pawe=C5=82=20Bylica?= <chfast@gmail.com>
Date: Mon, 13 Aug 2018 17:09:02 +0200
Subject: [PATCH] docs: Move EVMC description to markdown file

---
 Doxyfile            |  6 ++++--
 README.md           |  4 ++--
 docs/EVMC.md        | 51 +++++++++++++++++++++++++++++++++++++++++++++
 include/evmc/evmc.h | 17 ---------------
 4 files changed, 57 insertions(+), 21 deletions(-)
 create mode 100644 docs/EVMC.md

diff --git a/Doxyfile b/Doxyfile
index 2dd1583..d661526 100644
--- a/Doxyfile
+++ b/Doxyfile
@@ -99,7 +99,9 @@ WARN_LOGFILE           =
 #---------------------------------------------------------------------------
 # Configuration options related to the input files
 #---------------------------------------------------------------------------
-INPUT                  = include/evmc/
+INPUT                  = \
+    include/evmc/evmc.h include/evmc/loader.h include/evmc/helpers.h include/evmc/utils.h include/evmc/instructions.h \
+    docs/
 INPUT_ENCODING         = UTF-8
 FILE_PATTERNS          =
 RECURSIVE              = NO
@@ -176,7 +178,7 @@ QHG_LOCATION           =
 GENERATE_ECLIPSEHELP   = NO
 ECLIPSE_DOC_ID         = org.doxygen.Project
 DISABLE_INDEX          = NO
-GENERATE_TREEVIEW      = NO
+GENERATE_TREEVIEW      = YES
 ENUM_VALUES_PER_LINE   = 4
 TREEVIEW_WIDTH         = 250
 EXT_LINKS_IN_WINDOW    = NO
diff --git a/README.md b/README.md
index 71bb4e3..e7b057b 100644
--- a/README.md
+++ b/README.md
@@ -6,7 +6,7 @@
 > Ethereum Client-VM Connector API
 
 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].
+Ethereum Clients. On the EVM side it supports classic EVM1 and [eWASM].
 On the Client-side it defines the interface for EVM implementations 
 to access Ethereum environment and state.
 
@@ -49,7 +49,7 @@ Licensed under the [MIT License](LICENSE.md).
 [@axic]: https://github.com/axic
 [@chfast]: https://github.com/chfast
 [documentation]: https://ethereum.github.io/evmc
-[eWASM]: https://github.com/ewasm/design#ethereum-flavored-webassembly-ewasm-design
+[eWASM]: https://github.com/ewasm/design
 [evmjit]: https://github.com/ethereum/evmjit
 [Hera]: https://github.com/ewasm/hera
 [Gitter]: https://gitter.im/ethereum/evmc
diff --git a/docs/EVMC.md b/docs/EVMC.md
new file mode 100644
index 0000000..1431eca
--- /dev/null
+++ b/docs/EVMC.md
@@ -0,0 +1,51 @@
+# EVMC – Ethereum Client-VM Connector API {#mainpage}
+
+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 
+to access Ethereum environment and state.
+
+
+## Modules
+
+- [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). 
+- [EVMC Helpers](@ref helpers)
+   – a collection of utility functions for easier integration with EVMC.
+- [EVM Instructions](@ref instructions) 
+   – the library with collection of metrics for EVM1 instruction set.
+
+
+[eWASM]: https://github.com/ewasm/design
+
+
+@addtogroup EVMC
+
+## 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 
+   functions. This usually represents an Ethereum Client.
+   
+
+## Responsibilities
+
+### VM
+
+- Executes the code (obviously).
+- Calculates the running gas cost and manages the gas counter except the refund
+  counter.
+- Controls the call depth, including the exceptional termination of execution
+  in case the maximum depth is reached.
+  
+  
+### Host
+
+- Provides access to State.
+- Creates new accounts (with code being a result of VM execution).
+- Handles refunds entirely.
+- Manages the set of precompiled contracts and handles execution of messages
+  coming to them.
diff --git a/include/evmc/evmc.h b/include/evmc/evmc.h
index a6e8eb1..35b890b 100644
--- a/include/evmc/evmc.h
+++ b/include/evmc/evmc.h
@@ -5,23 +5,6 @@
  * Copyright 2018 Alex Beregszaszi, Pawel Bylica.
  * Licensed under the MIT License. See the LICENSE file.
  *
- * ## High level design rules
- *
- * 1. Pass function arguments and results by value.
- *    This rule comes from modern C++ and tries to avoid costly alias analysis
- *    needed for optimization. As the result we have a lots of complex structs
- *    and unions. And variable sized arrays of bytes cannot be passed by copy.
- * 2. The EVM operates on integers so it prefers values to be host-endian.
- *    On the other hand, LLVM can generate good code for byte swaping.
- *    The interface also tries to match host application "natural" endianess.
- *    I would like to know what endianess you use and where.
- *
- * ## Terms
- *
- * 1. EVM  -- an Ethereum Virtual Machine instance/implementation.
- * 2. Host -- an entity controlling the EVM. The Host requests code execution
- *            and responses to EVM queries by callback functions.
- *
  * @defgroup EVMC EVMC
  * @{
  */