vm: update and move README, refs. #339

README.md

@@ -25,7 +25,7 @@ A complete toolkit for the NEO blockchain, including:
 - [RPC node & client](https://github.com/nspcc-dev/neo-go/tree/master/docs/rpc.md)
 - [CLI tool](https://github.com/nspcc-dev/neo-go/blob/master/docs/cli.md)
 - [Smart contract compiler](https://github.com/nspcc-dev/neo-go/blob/master/docs/compiler.md)
-- [NEO virtual machine](https://github.com/nspcc-dev/neo-go/blob/master/pkg/vm/README.md)
+- [NEO virtual machine](https://github.com/nspcc-dev/neo-go/blob/master/docs/vm.md)
 
 # Getting started
 

docs/vm.md

@@ -4,28 +4,16 @@ A cross platform virtual machine implementation for `avm` compatible programs.
 
 # Installation
 
-## With neo-go
+VM is provided as part of neo-go binary, so usual neo-go build instructions
-Install dependencies.
+are applicable.
 
-`neo-go` uses [dep](https://github.com/golang/dep) as its dependency manager. After installing `deps` you can run:
+# Running the VM
-
-```
-make deps
-```
-
-Build the `neo-go` cli:
-
-```
-make build
-```
 
 Start the virtual machine:
 
 ```
-./bin/neo-go vm
+$ ./bin/neo-go vm
-```
 
-```
     _   ____________        __________      _    ____  ___
    / | / / ____/ __ \      / ____/ __ \    | |  / /  |/  /
   /  |/ / __/ / / / /_____/ / __/ / / /____| | / / /|_/ /
@@ -36,9 +24,6 @@ Start the virtual machine:
 NEO-GO-VM >
 ```
 
-## Standalone
-More information about standalone installation coming soon.
-
 # Usage
 
 ```
@@ -51,24 +36,39 @@ More information about standalone installation coming soon.
 
 NEO-GO-VM > help
 
-COMMAND    USAGE
+Commands:
-astack     show alt stack details
+  astack       Show alt stack contents
-break      place a breakpoint (> break 1)
+  break        Place a breakpoint
-cont       continue execution of the current loaded script
+  clear        clear the screen
-estack     show evaluation stack details
+  cont         Continue execution of the current loaded script
-exit       exit the VM prompt
+  estack       Show evaluation stack contents
-help       show available commands
+  exit         Exit the VM prompt
-ip         show the current instruction
+  help         display help
-istack     show invocation stack details
+  ip           Show current instruction
-loadavm    load an avm script into the VM (> load /path/to/script.avm)
+  istack       Show invocation stack contents
-loadgo     compile and load a .go file into the VM (> load /path/to/file.go)
+  loadavm      Load an avm script into the VM
-loadhex    load a hex string into the VM (> loadhex 006166 )
+  loadgo       Compile and load a Go file into the VM
-ops        show the opcodes of the current loaded program
+  loadhex      Load a hex-encoded script string into the VM
-run        execute the current loaded script
+  ops          Dump opcodes of the current loaded program
-step       step (n) instruction in the program (> step 10)
+  run          Execute the current loaded script
+  step         Step (n) instruction in the program
+
+
 ```
 
-### Loading in your script
+You can get help for each command and its parameters adding `help` as a
+parameter to the command:
+
+```
+NEO-GO-VM > step help
+
+Usage: step [<n>]
+<n> is optional parameter to specify number of instructions to run, example:
+> step 10
+
+```
+
+## Loading in your script
 
 To load an avm script into the VM:
 
@@ -111,7 +111,7 @@ NEO-GO-VM > run
 
 ```
 
-### Running programs with arguments
+## Running programs with arguments
 You can invoke smart contracts with arguments. Take the following ***roll the dice*** smartcontract as example. 
 
 ```
@@ -146,7 +146,10 @@ func rollDice(number int) {
 
 To invoke this contract we need to specify both the method and the arguments.
 
-The first parameter (called method or operation) is always of type string. Notice that arguments can have different types, to make the VM aware of the type we need to specify it when calling `run`:
+The first parameter (called method or operation) is always of type
+string. Notice that arguments can have different types, they can inferred
+automatically (please refer to the `run` command help), but in you need to
+pass parameter of specific type you can specify it in `run`'s arguments:
 
 ```
 NEO-GO-VM > run rollDice int:1
@@ -154,45 +157,52 @@ NEO-GO-VM > run rollDice int:1
 
 > The method is always of type string, hence we don't need to specify the type.
 
-To add more then 1 argument:
+To add more than 1 argument:
 
 ```
 NEO-GO-VM > run someMethod int:1 int:2 string:foo string:bar
 ```
 
-Current supported types:
+Currently supported types:
+- `bool (bool:false and bool:true)`
 - `int (int:1 int:100)`
 - `string (string:foo string:this is a string)` 
 
-### Debugging
+## Debugging
 The `neo-go-vm` provides a debugger to inspect your program in-depth.
 
+
+### Stepping through the program
 Step 4 instructions.
 
 ```
 NEO-GO-VM > step 4
-at breakpoint 4 (Opush4)
+at breakpoint 3 (DUPFROMALTSTACK)
-NEO-GO-VM 4 >
+NEO-GO-VM 3 >
 ```
 
 Using just `step` will execute 1 instruction at a time.
 
 ```
-NEO-GO-VM > step
+NEO-GO-VM 3 > step
-instruction pointer at 5 (Odup)
+at breakpoint 4 (PUSH0)
-NEO-GO-VM 5 >
+NEO-GO-VM 4 >
 ```
 
+### Breakpoints
+
 To place breakpoints:
 
 ```
 NEO-GO-VM > break 10
 breakpoint added at instruction 10
 NEO-GO-VM > cont
-at breakpoint 10 (Osetitem)
+at breakpoint 10 (SETITEM)
 NEO-GO-VM 10 > cont
 ```
 
+## Inspecting stack
+
 Inspecting the evaluation stack:
 
 ```