Added documentation and a few comments to the VM code.

Author: strinsberg

README.md

@@ -221,7 +221,7 @@ Pop the top two stack elements and push the result onto the stack. **multu** tre
 
 All versions pop the top two stack elements and divide the top - 1 stack element by the top. This is integer division as done in C so values that would result in fractions are rounded toward `0`. That means `-1.23` will be `-1` **NOT** `-2`. Use the unsigned versions if the values are being treated as unsigned. For example `0x10 / 0xff(-1)` is `0xf0(-16)` when signed, but it is just `0x00` when unsigned as `0xff` is much larger than `0x10`.
 
-### mod, dmod, dmod, dmodu
+### mod, dmod, modu, dmodu
 
 Pops the top two stack elements and takes top - 1 stack element mod by the top.
 

include/ltconst.h

@@ -19,12 +19,14 @@ extern const bool DEBUGGING;
 extern const ADDRESS END_MEMORY;
 extern const ADDRESS END_RETURN;
 extern const ADDRESS END_STACK;
-extern const WORD WORD_SIZE;
-extern const WORD BYTE_SIZE;
-extern const WORD BUFFER_SIZE;
-extern const WORD DEFAULT_SCALE;
-extern const WORDU SCALE_MAX;
-extern const DWORD SCALES[];
+
+extern const WORDU WORD_SIZE;         // number of bytes in a word
+extern const WORDU BYTE_SIZE;         // number of bits in a byte
+extern const WORDU BUFFER_SIZE;       // number of words in the buffer
+
+extern const WORDU DEFAULT_SCALE;     // index of default scale in scales
+extern const WORDU SCALE_MAX;         // length of the scales array
+extern const DWORDU SCALES[];         // scaling factors i.e. 10, 100 ...
 
 // Exit codes //
 extern const size_t EXIT_MEM;

include/ltio.h

@@ -4,9 +4,42 @@
 #include "ltconst.h"
 #include "stddef.h"
 
+/* Read the bytes of the program from the given file into the given memory
+ * array.
+ * On success returns the length of the program in words. On errors prints a
+ * message to stderr and returns 0. 
+ */
 size_t read_program(WORD* mem, const char* filename);
+
+/* Display a range of words from memory as space separated hex values.
+ * The range goes up to but not includeing end. I.e. [start, end).
+ * If debug is true it prints the range to stderr instead of stdout.
+ * I.e. display_range(memory, 1, 3);
+ * (out) 00aa bbcc
+ */
 void display_range(WORD* mem, ADDRESS start, ADDRESS end, bool debug);
+
+/* Print a null terminated string from memory.
+ * Assumes each word holds two characters, one in the top byte
+ * and one in the bottom byte of a 16 bit word. I.e. If a word is 0x6566
+ * then AB would be printed for that word.
+ * The given max is the maximum number of words to traverse if a null byte is
+ * not found. Null bytes can be in either position to stop the printing.
+ */
 void print_string(WORD* mem, ADDRESS start, ADDRESS max);
+
+/* Reads characters from stdin and stores them in memory starting from start.
+ * Will read until a newline is discovered or the max number of characters
+ * has been read. Every two characters will be packed into a word with the
+ * first character read being in the words top byte. Always leaves at least one
+ * null byte after the final read character. For an even number of characters
+ * the next word is set to 0. For an uneven number of characters the top byte
+ * of the last word is set to 0x00.
+ *
+ * TODO push a flag value onto the stack to indicate if max was reached before
+ * all input characters were read. This way it is possible to know that more
+ * input needs to be read.
+ */
 void read_string(WORD* mem, ADDRESS start, ADDRESS max);
 
 #endif

include/ltrun.h

@@ -4,6 +4,11 @@
 #include "ltconst.h"
 #include "stddef.h"
 
+/* All op codes for the VM.
+ * If new codes are added at this point they MUST be added to the end. The
+ * VM will still run fine if they are rearanged, but the tests depend on the
+ * current code assignment.
+ */
 enum op_codes { HALT=0,
   PUSH, POP, LOAD, STORE,  // 04
   FST, SEC, NTH,  // 07
@@ -45,9 +50,16 @@ enum op_codes { HALT=0,
   FMULT, FDIV, FMULTSC, FDIVSC,  // 63
 };
 
+// Some additional codes to track the direction of memory copies
 enum copy_codes { MEM_BUF = 0, BUF_MEM };
 
-
+/* Runs a program starting at position 0 in the given program memory.
+ * The length is the length of the program that has been loaded into memory
+ * and is used to calculate the positions of buffer and free memory pointers.
+ * The data and return stacks are expected to be empty. Any memory loaded into
+ * them before running this function will be lost.
+ * Returns an exit code based on the result of the program execution.
+ */
 size_t execute(WORD* memory, size_t length, WORD* data_stack, WORD* return_stack);
 
 #endif

src/ltconst.c

@@ -20,13 +20,13 @@ const ADDRESS END_MEMORY = 0xffff;
 const ADDRESS END_RETURN = 0x1000;
 const ADDRESS END_STACK = 0x1000;
 
-const WORD WORD_SIZE = 16;
-const WORD BYTE_SIZE = 8;
-const WORD BUFFER_SIZE = 0x0400;
+const WORDU WORD_SIZE = 16;
+const WORDU BYTE_SIZE = 8;
+const WORDU BUFFER_SIZE = 0x0400;
 
-const WORD DEFAULT_SCALE = 3;
+const WORDU DEFAULT_SCALE = 3;
 const WORDU SCALE_MAX = 10;
-const DWORD SCALES[ 10 ] = {
+const DWORDU SCALES[ 10 ] = {
   1, 10, 100, 1000, 10000, 100000,
   1000000, 10000000, 100000000,
   1000000000

src/ltio.c

@@ -81,7 +81,7 @@ void read_string(WORD* mem, ADDRESS start, ADDRESS max) {
       }
       mem[atemp] = two_chars;
       mem[atemp + 1] = 0;
-      break;
+      return;
 
     } else {
       if (first) {
@@ -94,5 +94,6 @@ void read_string(WORD* mem, ADDRESS start, ADDRESS max) {
       }
     }
   }
+  mem[atemp + 1] = 0;
 }
 

src/ltrun.c

@@ -7,49 +7,60 @@
 #include "string.h"
 
 size_t execute(WORD* memory, size_t length, WORD* data_stack, WORD* return_stack) {
+  // Declare and initialize memory pointer "registers"
   ADDRESS dsp, rsp, pc, bfp, fmp;
   dsp = 0;
   rsp = 0;
   pc = 0;
   bfp = length;
   fmp = length + BUFFER_SIZE;
 
+  // Declare some temporary "registers" for working with intermediate values
   ADDRESS atemp;
   WORD temp;
   WORDU utemp;
   DWORD dtemp;
   DWORDU udtemp;
 
+  // Run the program in memory
   bool run = true;
   while (run) {
+    // Print stack, op code, and pc before every execution
     if (DEBUGGING) {
       fprintf(stderr, "Stack: ");
       display_range(data_stack, 0x0001, dsp + 1, DEBUGGING);
       fprintf(stderr, "OP: %hx (%hu)\nPC: %hx (%hu)\n\n",
               memory[pc], memory[pc], pc, pc);
     }
 
+    // Catch some common pointer/address errors
     if (pc >= bfp) {
       fprintf(stderr,
               "Error: program counter out of bounds, pc: %hx, bfp: %hx\n",
               pc, bfp);
-      exit (EXIT_POB);
+      return EXIT_POB;
     } else if (dsp > 0x8000) {  // i.e. it has wrapped around into negatives
       fprintf(stderr, "Error: stack underflow, sp: %hx (%hd)\n", dsp, dsp);
-      exit (EXIT_SUF);
+      return EXIT_SUF;
     } else if (dsp > END_STACK) {
       fprintf(stderr, "Error: stack overflow, sp: %hx (%hd)\n", dsp, dsp);
-      exit (EXIT_SOF);
+      return EXIT_SOF;
     } else if (rsp > 0x8000) {  // i.e. it has wrapped around into negatives
       fprintf(stderr, "Error: return stack underflow, sp: %hx (%hd)\n",
               rsp, rsp);
-      exit (EXIT_RSUF);
+      return EXIT_RSUF;
     } else if (rsp > END_RETURN) {
       fprintf(stderr, "Error: return stack overflow, sp: %hx (%hd)\n",
               rsp, rsp);
-      exit (EXIT_RSOF);
+      return EXIT_RSOF;
     }
 
+    // Switch to cover each opcode. It is too long, but for simplicity and
+    // efficiency it is kept this way, with larger operations calling
+    // functions. The functions for things like unpacking and packing
+    // double words are declared as inline so they will be more efficient.
+    // Larger functions for things like io operations are regular functions
+    // because they are not really hurt by the function call.
     switch (memory[pc] & 0xff) {
       case HALT:
         run = false;
@@ -649,12 +660,15 @@ size_t execute(WORD* memory, size_t length, WORD* data_stack, WORD* return_stack
       /// BAD OP CODE ///
       default:
         fprintf(stderr, "Error: Unknown OP code: 0x%hx\n", memory[pc]);
-        exit(EXIT_OP);
+        return EXIT_OP;
     }
     pc++;
   }
 
-  // Test output
+  // When program is run for tests we print out the contents of the stack
+  // to stdout to check that the program ended in the expected state.
+  // Because we always increment dsp before pushing a value the true start of
+  // the stack is index 1 and not 0.
   if (TESTING) {
     display_range(data_stack, 0x0001, dsp + 1, false);
   }