docs: update readme (#84)

Author: eigmax

README.md

@@ -1 +1,46 @@
-# mips-circuits
+# ZKM
+
+ZKM is a general verifiable computing instructure based on [Plonky2](https://github.com/0xPolygonZero/plonky2) and the [MIPS microarchitecture](https://en.wikipedia.org/wiki/MIPS_architecture), empowering Ethereum as the Global Settlement Layer.
+
+# Building
+
+The zkm requires a latest nightly toolchain. Just run `cargo build --release` in zkm directory.
+
+# Running the examples
+
+An end-to-end example has been presented in [examples](./examples).
+
+# Guidance for external contributors
+
+Any kind of external contributions are encouraged and welcomed!
+
+## General guidance for your PR
+
+* The PR fixes a bug
+In the PR description, please clearly but briefly describe the bug, including how to reproduce, and the error/exception you got, and how your PR fixes the bugs.
+
+* The PR implements a new feature
+
+In the PR description, please clearly but briefly describe
+
+> 1. what the feature does
+> 2. the approach taken to implement it
+> 3. All PRs for new features must include a suitable test suite.
+
+* The PR improves performance
+
+To help filter out false positives, the PR description for a performance improvement must clearly identify
+
+> 1. the target bottleneck (only one per PR to avoid confusing things!)
+> 2. how performance is measured
+> 3. characteristics of the machine used (CPU, OS, #threads if appropriate) performance before and after the PR
+
+# Licenses
+
+LICENSE-APACHE is prefered. need to discuss.
+
+
+# Security
+
+This code has not yet been audited, and should not be used in any production systems.
+

examples/README.md

@@ -13,30 +13,30 @@ export GOMIPS=softfloat
 go build hello.go
 ```
 
-* Split the ELF hello into segments
+* Split the ELF hello into segments. Note that the flag `BLOCK_NO` is only necessary for minigeth.
 
 ```
-BASEDIR=test-vectors RUST_LOG=trace ELF_PATH=test-vectors/hello BLOCK_NO=13284491 SEG_OUTPUT=/tmp/output SEG_SIZE=262144 \
+BASEDIR=test-vectors RUST_LOG=info ELF_PATH=test-vectors/hello BLOCK_NO=13284491 SEG_OUTPUT=/tmp/output SEG_SIZE=262144 \
     cargo run --release --example zkmips split
 ```
 
 * Generate proof for each segment
 
 ```
-BASEDIR=test-vectors RUST_LOG=trace BLOCK_NO=13284491 SEG_FILE="/tmp/output/0" SEG_SIZE=262144 \
+BASEDIR=test-vectors RUST_LOG=info BLOCK_NO=13284491 SEG_FILE="/tmp/output/0" SEG_SIZE=262144 \
     cargo run --release --example zkmips prove
 ```
 
 * Aggregate proof
 
 ```
-BASEDIR=test-vectors RUST_LOG=trace BLOCK_NO=13284491 SEG_FILE="/tmp/output/0" SEG_FILE2="/tmp/output/1" SEG_SIZE=262144 \
+BASEDIR=test-vectors RUST_LOG=info BLOCK_NO=13284491 SEG_FILE="/tmp/output/0" SEG_FILE2="/tmp/output/1" SEG_SIZE=262144 \
     cargo run --release --example zkmips aggregate_proof
 ```
 
 * Aggregate proof all
 
 ```
-BASEDIR=test-vectors RUST_LOG=trace BLOCK_NO=13284491 SEG_FILE_DIR="/tmp/output" SEG_FILE_NUM=55 SEG_SIZE=262144 \
+BASEDIR=test-vectors RUST_LOG=info BLOCK_NO=13284491 SEG_FILE_DIR="/tmp/output" SEG_FILE_NUM=55 SEG_SIZE=262144 \
     cargo run --release --example zkmips aggregate_proof_all
 ```

src/cpu/bootstrap_kernel.rs

@@ -190,7 +190,6 @@ pub(crate) fn check_memory_page_hash<F: Field>(
     // The Keccak sponge CTL uses memory value columns for its inputs and outputs.
     cpu_row.mem_channels[0].value[0] = F::ZERO; // context
     cpu_row.mem_channels[1].value[0] = F::from_canonical_usize(Segment::Code as usize);
-    //cpu_row.mem_channels[2].value[0] = F::from_canonical_usize(page_data_addr[0].virt);
     let final_idx = page_addr_value_byte_be.len() / KECCAK_RATE_BYTES * KECCAK_RATE_U32S;
     cpu_row.mem_channels[2].value[0] = F::from_canonical_usize(page_data_addr[final_idx].virt);
     cpu_row.mem_channels[3].value[0] = F::from_canonical_usize(page_addr_value_byte_be.len()); // len