wasm: documents memory constants

This documents memory constants. Somewhere, we should document what the
default memory size is (seems 2 pages so 128KB), as that determines the
initial heap size (which is a portion of that).

Signed-off-by: Adrian Cole <adrian@tetrate.io>

src/runtime/arch_tinygowasm.go

@@ -20,21 +20,46 @@ var heapStartSymbol [0]byte
 //go:extern __global_base
 var globalsStartSymbol [0]byte
 
+const (
+	// wasmMemoryIndex is always zero until the multi-memory feature is used.
+	//
+	// See https://github.com/WebAssembly/multi-memory
+	wasmMemoryIndex = 0
+
+	// wasmPageSize is the size of a page in WebAssembly's 32-bit memory. This
+	// is also its only unit of change.
+	//
+	// See https://www.w3.org/TR/wasm-core-1/#page-size
+	wasmPageSize = 64 * 1024
+)
+
+// wasm_memory_size invokes the "memory.size" instruction, which returns the
+// current size to the memory at the given index (always wasmMemoryIndex), in
+// pages.
+//
 //export llvm.wasm.memory.size.i32
 func wasm_memory_size(index int32) int32
 
+// wasm_memory_grow invokes the "memory.grow" instruction, which attempts to
+// increase the size of the memory at the given index (always wasmMemoryIndex),
+// by the delta (in pages). This returns the previous size on success of -1 on
+// failure.
+//
 //export llvm.wasm.memory.grow.i32
 func wasm_memory_grow(index int32, delta int32) int32
 
 var (
-	heapStart    = uintptr(unsafe.Pointer(&heapStartSymbol))
-	heapEnd      = uintptr(wasm_memory_size(0) * wasmPageSize)
+	// heapStart is the current memory offset which starts the heap. The heap
+	// extends from this offset until heapEnd (exclusive).
+	heapStart = uintptr(unsafe.Pointer(&heapStartSymbol))
+
+	// heapEnd is the current memory length in bytes.
+	heapEnd = uintptr(wasm_memory_size(wasmMemoryIndex) * wasmPageSize)
+
 	globalsStart = uintptr(unsafe.Pointer(&globalsStartSymbol))
 	globalsEnd   = uintptr(unsafe.Pointer(&heapStartSymbol))
 )
 
-const wasmPageSize = 64 * 1024
-
 func align(ptr uintptr) uintptr {
 	// Align to 16, which is the alignment of max_align_t:
 	// https://godbolt.org/z/dYqTsWrGq
@@ -48,14 +73,14 @@ func getCurrentStackPointer() uintptr
 // otherwise.
 func growHeap() bool {
 	// Grow memory by the available size, which means the heap size is doubled.
-	memorySize := wasm_memory_size(0)
-	result := wasm_memory_grow(0, memorySize)
+	memorySize := wasm_memory_size(wasmMemoryIndex)
+	result := wasm_memory_grow(wasmMemoryIndex, memorySize)
 	if result == -1 {
 		// Grow failed.
 		return false
 	}
 
-	setHeapEnd(uintptr(wasm_memory_size(0) * wasmPageSize))
+	setHeapEnd(uintptr(wasm_memory_size(wasmMemoryIndex) * wasmPageSize))
 
 	// Heap has grown successfully.
 	return true