.

2025-07-16 13:00:37 +03:00
commit 7894b48931
806 changed files with 162532 additions and 0 deletions
@@ -0,0 +1,183 @@
+// This file is part of www.nand2tetris.org
+// and the book "The Elements of Computing Systems"
+// by Nisan and Schocken, MIT Press.
+// File name: projects/12/MemoryTest/Main.jack
+
+/** Test program for the OS Memory class. */
+class Main {
+
+    /** Test Memory.peek(), poke(), alloc() and deAlloc().
+     *
+     *  This test is also a diagnostic.  RAM[17000] is incremented before and
+     *  after every call so that the failure point can be accurately determined
+     *  when using command line testing.  Return values from all alloc() calls
+     *  are also stored in the test results to aid debugging.
+     */
+    function void main() {
+        var int temp;
+        var Array a, b, c, out;
+
+        let out = 17000;     // Address where test results will be stored.
+
+        // Test poke() and peek().
+
+        let out[0] = 10;                    // poke test
+        do Memory.poke(out + 1, 333);       // RAM[17001] = 333
+
+        let out[0] = 11;                    // peek test
+        let temp = Memory.peek(out + 1);
+        let out[2] = temp + 1;              // RAM[17002] = 334
+        let out[0] = 12;                    // peek/poke test complete
+
+        // Allocate a memory block.
+        // Validate that the returned block is entirely within the heap,
+        // Test aborts if the block is not valid.
+
+        let out[0] = 20;
+        let a = Memory.alloc(20);
+        let out[3] = a;                     // RAM[17003] = block address
+
+        let out[0] = 21;
+        do Main.checkRange(a, 20);
+        let out[0] = 22;
+
+        // Allocate a SMALLER memory block.
+        // Validate that the returned block is entirely within the heap,
+        // and that it does not overlap block 'a'.
+        // Test aborts if the block is not valid or overlaps.
+        //
+        // Common failure: first block was not removed from free list so space
+        // for this block was found within the first block.
+
+        let out[0] = 30;
+        let b = Memory.alloc(3);
+        let out[4] = b;                     // RAM[17004] = block address
+
+        let out[0] = 31;
+        do Main.checkRange(b, 3);
+        let out[0] = 32;
+        do Main.checkOverlap(b, 3, a, 3);
+        let out[0] = 33;
+
+        // Allocate a memory block.
+        // Validate that the returned block is entirely within the heap,
+        // and that it does not overlap blocks 'a' or 'b'.
+        // Test aborts if the block is not valid or overlaps.
+
+        let out[0] = 40;
+        let c = Memory.alloc(500);
+        let out[5] = c;                     // RAM[17005] = block address
+
+        let out[0] = 41;
+        do Main.checkRange(c, 500);
+        let out[0] = 42;
+        do Main.checkOverlap(c, 500, a, 3);
+        let out[0] = 43;
+        do Main.checkOverlap(c, 500, b, 3);
+        let out[0] = 44;
+
+        // Deallocate blocks 'a' and 'b', retaining 'c'.
+        //
+        // Common failure: free list corrupted by deAlloc().
+
+        let out[0] = 50;
+        do Memory.deAlloc(a);
+
+        let out[0] = 51;
+        do Memory.deAlloc(b);
+        let out[0] = 52;
+
+        // Allocate a memory block.
+        // Validate that the returned block is entirely within the heap,
+        // and that it does not overlap blocks 'c'.
+        // Test aborts if the block is not valid or overlaps.
+        //
+        // Common failure: free list corrupted by deAlloc().
+
+        let out[0] = 60;
+        let b = Memory.alloc(3);
+        let out[6] = b;                     // RAM[17006] = block address
+
+        let out[0] = 61;
+        do Main.checkRange(b, 3);
+        let out[0] = 62;
+        do Main.checkOverlap(b, 3, c, 500);
+        let out[0] = 63;
+
+        // Deallocate blocks 'b' and 'c'.
+
+        let out[0] = 70;
+        do Memory.deAlloc(c);
+
+        let out[0] = 71;
+        do Memory.deAlloc(b);
+        let out[0] = 72;
+
+        // Test that deallocated blocks are placed on the free list and can
+        // be reused.
+
+        let out[0] = 70;
+        let a = Memory.alloc(8000);
+        let out[7] = a;                     // RAM[17007] = block address
+
+        let out[0] = 71;
+        do Main.checkRange(a, 8000);
+
+        let out[0] = 72;
+        do Memory.deAlloc(a);
+
+        let out[0] = 73;
+        let a = Memory.alloc(7000);
+
+        let out[0] = 74;
+        do Main.checkRange(a, 7000);
+
+        let out[0] = 75;
+        do Memory.deAlloc(a);
+        let out[8] = a;                     // RAM[17008] = block address
+
+        // Test complete.
+        let out[0] = 100;
+
+        // At this point all allocated blocks have been deallocated.
+        //
+        // You can inspect the free list and confirm that all of the heap is
+        // contained in the free segments.
+        //
+        // If you implemented defragmentation in dealloc(), the free list
+        // should contain only one segment, consisting of the entire heap.
+
+        return;
+    }
+
+
+    /** Check that block a(a_len) is in the heap.
+     *
+     *  If the block begins or ends outside of the heap, calls Sys.halt()
+     */
+    function void checkRange(int a, int a_len) {
+        var int a_high;
+        let a_high = (a + a_len)-1;
+        if ((a < 2048) | ((a_high) > 16383)) {
+            // Block is not entirely within heap.
+            do Sys.halt();
+        }
+        return;
+    }
+
+    /** Check that block a(a_len) does not overlap block b(b_len).
+     *  Assumes that both blocks have been range checked.
+     *
+     *  If the blocks overlap, calls Sys.halt()
+     */
+    function void checkOverlap(int a, int a_len, int b, int b_len) {
+        var int a_high, b_high;
+        let a_high = (a + a_len)-1;
+        let b_high = (b + b_len)-1;
+        if ( ~ ((a > b_high) | (a_high < b))) {
+            // Block overlaps excluded range.
+            do Sys.halt();
+        }
+        return;
+    }
+}
@@ -0,0 +1,467 @@
+function Main.main 5
+push constant 17000
+pop local 4
+push local 4
+push constant 0
+push constant 10
+pop temp 1
+add
+pop pointer 1
+push temp 1
+pop that 0
+push local 4
+push constant 1
+add
+push constant 333
+call Memory.poke 2
+pop temp 0
+push local 4
+push constant 0
+push constant 11
+pop temp 1
+add
+pop pointer 1
+push temp 1
+pop that 0
+push local 4
+push constant 1
+add
+call Memory.peek 1
+pop local 0
+push local 4
+push constant 2
+push local 0
+push constant 1
+add
+pop temp 1
+add
+pop pointer 1
+push temp 1
+pop that 0
+push local 4
+push constant 0
+push constant 12
+pop temp 1
+add
+pop pointer 1
+push temp 1
+pop that 0
+push local 4
+push constant 0
+push constant 20
+pop temp 1
+add
+pop pointer 1
+push temp 1
+pop that 0
+push constant 20
+call Memory.alloc 1
+pop local 1
+push local 4
+push constant 3
+push local 1
+pop temp 1
+add
+pop pointer 1
+push temp 1
+pop that 0
+push local 4
+push constant 0
+push constant 21
+pop temp 1
+add
+pop pointer 1
+push temp 1
+pop that 0
+push local 1
+push constant 20
+call Main.checkRange 2
+pop temp 0
+push local 4
+push constant 0
+push constant 22
+pop temp 1
+add
+pop pointer 1
+push temp 1
+pop that 0
+push local 4
+push constant 0
+push constant 30
+pop temp 1
+add
+pop pointer 1
+push temp 1
+pop that 0
+push constant 3
+call Memory.alloc 1
+pop local 2
+push local 4
+push constant 4
+push local 2
+pop temp 1
+add
+pop pointer 1
+push temp 1
+pop that 0
+push local 4
+push constant 0
+push constant 31
+pop temp 1
+add
+pop pointer 1
+push temp 1
+pop that 0
+push local 2
+push constant 3
+call Main.checkRange 2
+pop temp 0
+push local 4
+push constant 0
+push constant 32
+pop temp 1
+add
+pop pointer 1
+push temp 1
+pop that 0
+push local 2
+push constant 3
+push local 1
+push constant 3
+call Main.checkOverlap 4
+pop temp 0
+push local 4
+push constant 0
+push constant 33
+pop temp 1
+add
+pop pointer 1
+push temp 1
+pop that 0
+push local 4
+push constant 0
+push constant 40
+pop temp 1
+add
+pop pointer 1
+push temp 1
+pop that 0
+push constant 500
+call Memory.alloc 1
+pop local 3
+push local 4
+push constant 5
+push local 3
+pop temp 1
+add
+pop pointer 1
+push temp 1
+pop that 0
+push local 4
+push constant 0
+push constant 41
+pop temp 1
+add
+pop pointer 1
+push temp 1
+pop that 0
+push local 3
+push constant 500
+call Main.checkRange 2
+pop temp 0
+push local 4
+push constant 0
+push constant 42
+pop temp 1
+add
+pop pointer 1
+push temp 1
+pop that 0
+push local 3
+push constant 500
+push local 1
+push constant 3
+call Main.checkOverlap 4
+pop temp 0
+push local 4
+push constant 0
+push constant 43
+pop temp 1
+add
+pop pointer 1
+push temp 1
+pop that 0
+push local 3
+push constant 500
+push local 2
+push constant 3
+call Main.checkOverlap 4
+pop temp 0
+push local 4
+push constant 0
+push constant 44
+pop temp 1
+add
+pop pointer 1
+push temp 1
+pop that 0
+push local 4
+push constant 0
+push constant 50
+pop temp 1
+add
+pop pointer 1
+push temp 1
+pop that 0
+push local 1
+call Memory.deAlloc 1
+pop temp 0
+push local 4
+push constant 0
+push constant 51
+pop temp 1
+add
+pop pointer 1
+push temp 1
+pop that 0
+push local 2
+call Memory.deAlloc 1
+pop temp 0
+push local 4
+push constant 0
+push constant 52
+pop temp 1
+add
+pop pointer 1
+push temp 1
+pop that 0
+push local 4
+push constant 0
+push constant 60
+pop temp 1
+add
+pop pointer 1
+push temp 1
+pop that 0
+push constant 3
+call Memory.alloc 1
+pop local 2
+push local 4
+push constant 6
+push local 2
+pop temp 1
+add
+pop pointer 1
+push temp 1
+pop that 0
+push local 4
+push constant 0
+push constant 61
+pop temp 1
+add
+pop pointer 1
+push temp 1
+pop that 0
+push local 2
+push constant 3
+call Main.checkRange 2
+pop temp 0
+push local 4
+push constant 0
+push constant 62
+pop temp 1
+add
+pop pointer 1
+push temp 1
+pop that 0
+push local 2
+push constant 3
+push local 3
+push constant 500
+call Main.checkOverlap 4
+pop temp 0
+push local 4
+push constant 0
+push constant 63
+pop temp 1
+add
+pop pointer 1
+push temp 1
+pop that 0
+push local 4
+push constant 0
+push constant 70
+pop temp 1
+add
+pop pointer 1
+push temp 1
+pop that 0
+push local 3
+call Memory.deAlloc 1
+pop temp 0
+push local 4
+push constant 0
+push constant 71
+pop temp 1
+add
+pop pointer 1
+push temp 1
+pop that 0
+push local 2
+call Memory.deAlloc 1
+pop temp 0
+push local 4
+push constant 0
+push constant 72
+pop temp 1
+add
+pop pointer 1
+push temp 1
+pop that 0
+push local 4
+push constant 0
+push constant 70
+pop temp 1
+add
+pop pointer 1
+push temp 1
+pop that 0
+push constant 8000
+call Memory.alloc 1
+pop local 1
+push local 4
+push constant 7
+push local 1
+pop temp 1
+add
+pop pointer 1
+push temp 1
+pop that 0
+push local 4
+push constant 0
+push constant 71
+pop temp 1
+add
+pop pointer 1
+push temp 1
+pop that 0
+push local 1
+push constant 8000
+call Main.checkRange 2
+pop temp 0
+push local 4
+push constant 0
+push constant 72
+pop temp 1
+add
+pop pointer 1
+push temp 1
+pop that 0
+push local 1
+call Memory.deAlloc 1
+pop temp 0
+push local 4
+push constant 0
+push constant 73
+pop temp 1
+add
+pop pointer 1
+push temp 1
+pop that 0
+push constant 7000
+call Memory.alloc 1
+pop local 1
+push local 4
+push constant 0
+push constant 74
+pop temp 1
+add
+pop pointer 1
+push temp 1
+pop that 0
+push local 1
+push constant 7000
+call Main.checkRange 2
+pop temp 0
+push local 4
+push constant 0
+push constant 75
+pop temp 1
+add
+pop pointer 1
+push temp 1
+pop that 0
+push local 1
+call Memory.deAlloc 1
+pop temp 0
+push local 4
+push constant 8
+push local 1
+pop temp 1
+add
+pop pointer 1
+push temp 1
+pop that 0
+push local 4
+push constant 0
+push constant 100
+pop temp 1
+add
+pop pointer 1
+push temp 1
+pop that 0
+push constant 0
+return
+function Main.checkRange 1
+push argument 0
+push argument 1
+add
+push constant 1
+sub
+pop local 0
+push argument 0
+push constant 2048
+lt
+push local 0
+push constant 16383
+gt
+or
+not
+if-goto L0
+call Sys.halt 0
+pop temp 0
+goto L1
+label L0
+label L1
+push constant 0
+return
+function Main.checkOverlap 2
+push argument 0
+push argument 1
+add
+push constant 1
+sub
+pop local 0
+push argument 2
+push argument 3
+add
+push constant 1
+sub
+pop local 1
+push argument 0
+push local 1
+gt
+push local 0
+push argument 2
+lt
+or
+not
+not
+if-goto L2
+call Sys.halt 0
+pop temp 0
+goto L3
+label L2
+label L3
+push constant 0
+return
@@ -0,0 +1,2 @@
+|RAM[17000|RAM[17001|RAM[17002|RAM[17003|RAM[17004|RAM[17005|RAM[17006|RAM[17007|RAM[17008|
+|     100 |     333 |     334 |*********|*********|*********|*********|*********|*********|
@@ -0,0 +1,18 @@
+// This file is part of www.nand2tetris.org
+// and the book "The Elements of Computing Systems"
+// by Nisan and Schocken, MIT Press.
+// File name: projects/12/MemoryTest/MemoryDiag/MemoryDiag.tst
+
+echo "At the end of this test it is normal to see some pixels set on the screen";
+load,
+output-file MemoryDiag.out,
+compare-to MemoryDiag.cmp,
+output-list RAM[17000]%D2.6.1 RAM[17001]%D2.6.1 RAM[17002]%D2.6.1
+    RAM[17003]%D2.6.1 RAM[17004]%D2.6.1 RAM[17005]%D2.6.1 RAM[17006]%D2.6.1
+    RAM[17007]%D2.6.1 RAM[17008]%D2.6.1;
+
+repeat 1000000 {
+  vmstep;
+}
+
+output;
@@ -0,0 +1,55 @@
+<html>
+<h4>MemoryDiag is both a pass/fail test and a diagnostic.</h4>
+<p>
+MemoryDiag tests the following:
+<ol>
+<li>Memory.peek() and Memory.poke() read from and write to the specified memory address.</li>
+<li>Memory.alloc() returns RAM blocks that are fully contained within the heap address range 2048-16383.</li>
+<li>Memory.alloc() does not return RAM blocks that overlap each other.</li>
+<li>RAM blocks deallocated by Memory.deAlloc() are made available for Memory.alloc() to reuse.</li>
+</ol>
+The block reuse test allocates and deallocates an 8000 word block.  It then tries to allocates a 7000 word block which must be allocated from the deallocated 8000 word block.  If the 8000 word block is not available for reuse, there will only be about 6300 words available in the heap so you will get an ERR6.
+<p>
+<i>At the end of this test it is normal to see some pixels set on the screen.</i>  This is because the results of the test are written to RAM[17000]&nbsp;&ndash; RAM[17008] which is in the Screen memory.  MemoryDiag does not put its results in the first 16K of RAM because it must not interfere with the Memory.jack that is being tested.
+
+
+<h4>Using MemoryDiag as a diagnostic</h4>
+
+RAM[17000] is set to a unique value before every system call and address validation.  This allows the exact failure location in the test to be identified when automated testing is used.  At the end of the test, RAM[17000] is set to 100.
+<p>
+When the test fails to compare, look at the MemoryDiag.out file and note the RAM[17000] value.  This is the test <i>step</i> that failed.  Look through the Main.jack code and find the corresponding<br>
+&emsp;&emsp;<tt>let out[0] = <i>step</i>;</tt><br>
+statement.  The function immediately following this statement is where the failure occurred.
+<p>
+For example, if RAM[17000] is 51, the<br>
+&emsp;&emsp;<tt>do Memory.deAlloc(b);</tt><br>
+call did not return.  Either there was a simulation error like a bad address or deAlloc() got stuck in a loop.
+
+
+<h4>Sample MemoryDiag output files</h4>
+
+<i>Note that RAM[17003]&nbsp;&ndash; RAM[17008] are "don't care" values in the MemoryDiag.cmp file.</i>
+<p>
+Supplied Memory.vm passes:
+<pre style="padding-left:2em;">
+|RAM[17000|RAM[17001|RAM[17002|RAM[17003|RAM[17004|RAM[17005|RAM[17006|RAM[17007|RAM[17008|
+|     100 |     333 |     334 |    2050 |    2072 |    2077 |    2050 |    2050 |    2050 |
+</pre>
+Memory.Jack using the Coursera implementation passes:
+<pre style="padding-left:2em;">
+|RAM[17000|RAM[17001|RAM[17002|RAM[17003|RAM[17004|RAM[17005|RAM[17006|RAM[17007|RAM[17008|
+|     100 |     333 |     334 |   16364 |   16359 |   15857 |   15852 |    7850 |    8850 |
+</pre>
+Broken Memory.jack fails (alloc() returns duplicate block address):
+<pre style="padding-left:2em;">
+|RAM[17000|RAM[17001|RAM[17002|RAM[17003|RAM[17004|RAM[17005|RAM[17006|RAM[17007|RAM[17008|
+|      32 |     333 |     334 |    2050 |    2050 |       0 |       0 |       0 |       0 |
+</pre>
+Broken Memory.jack fails (deAlloc() does not recycle memory blocks):
+<pre style="padding-left:2em;">
+|RAM[17000|RAM[17001|RAM[17002|RAM[17003|RAM[17004|RAM[17005|RAM[17006|RAM[17007|RAM[17008|
+|      73 |     333 |     334 |   16364 |   16359 |   15857 |   15852 |    7850 |       0 |
+</pre>
+
+</html>
+<p>