cleanup

Author: yangdanny97

README.md

@@ -31,7 +31,7 @@ The test suite includes both static validation of generated/annotated ASTs, as w
   - [Mono](https://www.mono-project.com/)
   - Tested with Mono 6.12
 - WASM Backend Requirements:
-  - [WebAssembly Binary Toolkit (wabt)](https://github.com/WebAssembly/wabt)
+  - [WebAssembly Binary Toolkit (wabt)](https://github.com/WebAssembly/wabt), specifically the `wat2wasm` tool
 
 ## Usage
 
@@ -94,7 +94,7 @@ Note that in the above example commands & the `demo_jvm.sh` script all expect th
 
 ## CIL Backend Notes:
 
-The CIL backend for this compiler outputs CIL bytecode in plaintext formatted for the Mono ilsam assembler:
+The CIL backend for this compiler outputs CIL bytecode in plaintext formatted for the Mono `ilasm` assembler:
 1. Use this compiler to generate plaintext bytecode 
     - Format:  `python3 main.py --mode cil <input file> <output dir>`
     - Example: `python3 main.py --mode cil tests/runtime/binary_tree.py .`
@@ -110,32 +110,43 @@ The `demo_cil.sh` script is a useful utility to compile and run files with the C
 
 ## WASM Backend Notes:
 
-This is WIP, not all features are supported. 
+This is WIP, not all features are supported (the binary tree example itself actually does not work, but you can try another one). 
 
-Features:
+The WASM backend for this compiler outputs WASM in plaintext `.wat` format which can be converted to `.wasm` using `wat2wasm`:
+1. Use this compiler to generate plaintext WebAssembly
+    - Format:  `python3 main.py --mode wasm <input file> <output dir>`
+    - Example: `python3 main.py --mode wasm tests/runtime/binary_tree.py .`
+2. Run `wat2wasm` assembler to generate `.wasm` files
+    - Format:  `wat2wasm <.wat file> -o <.wasm file>`
+    - Example: `wat2wasm binary_tree.wat -o binary_tree.wasm`
+3. Run the `.wasm` files using a minimal JS runtime
+    - Example: `node wasm.js <.wasm file>`
+    - Example: `node wasm.js binary_tree.wasm`
+
+The `demo_wasm.sh` script is a useful utility to compile and run files with the WASM backend with a single command (provide the path to the input source file as an argument). 
+- To run the same example as above, run `./demo_wasm.sh tests/runtime/binary_tree.py`
+
+### WASM Backend - Supported Features:
 - int, bool, string, list
 - most operators
 - assignment
 - control flow
 - stdlib: print, len, and assert
 - globals
 
-Unsupported/TODO:
+### WASM Backend - Unsupported Features:
 - class/object
 - nonlocal (partial)
-- stdlib: input
+- stdlib: input (node.js does not have synchronous I/O out of the box so this is difficult)
 
-Memory format:
+### WASM Backend - Memory Format, Safety, and Management:
 
 - strings (utf-8) - first 4 bytes for length, followed by 1 byte for each character
 - lists - first 4 bytes for length, followed by 8 bytes for each element
 - ints - i64
-- pointers (objects, strings, lists) - i32
-- None - 0 (i32)
-
-Strings and lists are stored in the heap, aligned to 8 bytes. Note that memory does not get freed/garbage collected, so memory will run out for long-running programs. This is especially a problem with string iteration and string/list concatenation, since indexing a string in Chocopy requires a new string to be allocated.
+- pointers (objects, strings, lists) - i32, where `None` is 0
 
-To provide memory safety, string/list indexing have bounds checking and list operations have a null-check, which crashes the program with a generic "unreachable" instruction.
+Strings, lists, objects, and refs holding nonlocals are stored in the heap, aligned to 8 bytes. Right now, memory does not get freed/garbage collected once it is allocated. To provide memory safety, string/list indexing have bounds checking and list operations have a null-check, which crashes the program with a generic "unreachable" instruction.
 
 ## FAQ
 

compiler/wasm_backend.py

@@ -681,6 +681,7 @@ def stdlib(self) -> str:
     (func $nullthrow (param $addr i32) (result i32)
         local.get $addr
         i32.eqz
+        ;; throw if $addr == 0
         (if
             (then
                 unreachable
@@ -695,6 +696,7 @@ def stdlib(self) -> str:
         local.get $idx
         i32.gt_s
         i32.eqz
+        ;; throw if !($len > $idx)
         (if
             (then
                 unreachable
@@ -703,6 +705,7 @@ def stdlib(self) -> str:
         i32.const 0
         local.get $idx
         i32.gt_s
+        ;; throw if 0 > $idx
         (if
             (then
                 unreachable
@@ -794,9 +797,11 @@ def stdlib(self) -> str:
         local.get $left
         i32.load
         local.tee $length
+        ;; compare $length with len of $right
         local.get $right
         i32.load
         i32.eq
+        ;; only compare contents if lengths are equal
         (if
             (then
                 i32.const 0
@@ -807,17 +812,21 @@ def stdlib(self) -> str:
                         local.get $length
                         i32.lt_s
                         i32.eqz
+                        ;; get left char
                         br_if $block
                         local.get $left
                         local.get $idx
                         call $get_char
+                        ;; get right char
                         local.get $right
                         local.get $idx
                         call $get_char
+                        ;; $result = $result && left char == right char
                         i32.eq
                         local.get $result
                         i32.and
                         local.set $result
+                        ;; if !$result then break
                         local.get $result
                         i32.eqz
                         br_if $block

wasm.js

@@ -1,6 +1,18 @@
-const wasm_path = process.argv[2];
+/**
+ * Runtime support for running WASM compiled from Chocopy
+ * 
+ * This is a very minimal runtime since the goal was to implement as much as 
+ * possible directly in WASM. 
+ * 
+ * The only imports from JS to WASM are for `console.log` and `console.assert`,
+ * and the latter isn't even strictly necessary.
+ * 
+ * The memory buffer is instantiated by JS, but after that it's never written 
+ * to and only used to print strings. 
+ */
+
 
-// utils for pretty-printing ints, bools, strings
+const wasm_path = process.argv[2];
 
 function logString(offset) {
     // first 4 bytes is the length
@@ -22,7 +34,10 @@ function logBool(val) {
     console.log(val !== 0);
 }
 
-const memory = new WebAssembly.Memory({ initial: 10, maximum: 100 });
+const memory = new WebAssembly.Memory({
+    initial: 10,
+    maximum: 100
+});
 
 const importObject = {
     imports: {
@@ -31,7 +46,9 @@ const importObject = {
         logBool: x => logBool(x),
         assert: x => console.assert(x)
     },
-    js: { mem: memory },
+    js: {
+        mem: memory
+    },
 };
 
 const fs = require('fs');