status-im
/
evmc
mirror of https://github.com/status-im/evmc.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

Improve documentation for EVM tracing

This commit is contained in:
Paweł Bylica 2018-06-19 10:16:08 +02:00
parent 9e31e93fec
commit 59dc54ef5d
No known key found for this signature in database
GPG Key ID: 7A0C037434FE77EF
1 changed files with 25 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

43
include/evmc/evmc.h
View File

@ -675,18 +675,18 @@ enum evmc_revision
/**
* Generates and executes machine code for given EVM bytecode.
* Executes the given EVM bytecode using the input in the message
*
* All the fun is here. This function actually does something useful.
* This function MAY be invoked multiple times for a single EVM instance.
*
* @param instance A EVM instance.
* @param context The pointer to the Host execution context to be passed
* to callback functions. @see ::evmc_context.
* @param rev Requested EVM specification revision.
* @param msg Call parameters. @see ::evmc_message.
* @param code Reference to the bytecode to be executed.
* @param code_size The length of the bytecode.
* @return All execution results.
* @param instance The EVM instance.
* @param context The pointer to the Client execution context to be passed
* to the callback functions. @see ::evmc_context.
* @param rev Requested EVM specification revision.
* @param msg Call parameters. @see ::evmc_message.
* @param code Reference to the bytecode to be executed.
* @param code_size The length of the bytecode.
* @return All execution results.
*/
typedef struct evmc_result (*evmc_execute_fn)(struct evmc_instance* instance,
struct evmc_context* context,
@ -703,22 +703,24 @@ struct evmc_tracer_context;
* The callback to trace instructions execution in an EVM.
*
* This function informs the Client what instruction has been executed in the EVM implementation
* and what are the results of the execution this particular instruction.
* and what are the results of executing this particular instruction.
* The message level information (like call depth, destination address, etc.) are not provided here.
* This piece of information can be acquired by inspecting messages being sent to the EVM in
* ::evmc_execute_fn and the results of the messages execution.
*
* @param context The pointer to the Client-side tracing context. This allows to
* implement the tracer in OOP manner.
* @param step The instruction counter for the current message.
* @param code_offset The instruction possition in the code.
* @param step The instruction counter: number of instructions executed.
* This counter starts from 0 for every message passed to
* ::evmc_execute_fn.
* @param code_offset The current instruction position in the code.
* @param status_code The status code of the instruction execution.
* @param gas_left The amount of the gas left after the instruction execution.
* @param stack_num_items The current EVM stack height.
* @param stack_num_items The current EVM stack height after the instruction execution.
* @param pushed_stack_item The top EVM stack item pushed as the result of the instruction
* execution. This value is null when the instruction does not push
* anything to the stack.
* @param memory_size The current size of the EVM memory.
* @param memory_size The size of the EVM memory after the instruction execution.
* @param changed_memory_offset The beginning of the memory area modified as the result of
* the instruction execution.
* @param changed_memory_size The size of the memory area modified as the result of
@ -741,13 +743,18 @@ typedef void (*evmc_trace_callback)(struct evmc_tracer_context* context,
/**
* Sets the EVM instruction tracer.
*
* When the tracer is set in the EVM instance, the EVM SHOULD callback the tracer with information
* When the tracer is set in the EVM instance, the EVM SHOULD call back the tracer with information
* about instructions execution in the EVM.
* @see ::evmc_trace_callback.
*
* This will overwrite the previous settings (the callback and the context).
*
* @param instance The EVM instance.
* @param callback The tracer callback function.
* @param context The Client-side tracer context.
* @param callback The tracer callback function. This argument MAY be NULL to disable previously
* set tracer.
* @param context The Client-side tracer context. This argument MAY be NULL in case the tracer
* does not require any context. This argument MUST be NULL if the callback
* argument is NULL.
*/
typedef void (*evmc_set_tracer_fn)(struct evmc_instance* instance,
evmc_trace_callback callback,