From 2e006fdfdd0b7bc65b2ca7a7bb363a8c54316a9d Mon Sep 17 00:00:00 2001
From: Dan White <dan@whiteaudio.com>
Date: Tue, 7 May 2013 12:59:03 -0500
Subject: [PATCH] msp4th: update docs

---
 msp4th/main.c | 58 ++++++++++++++++++++++++++++++++++-----------------
 1 file changed, 39 insertions(+), 19 deletions(-)

diff --git a/msp4th/main.c b/msp4th/main.c
index 24b7e5b..aea5470 100644
--- a/msp4th/main.c
+++ b/msp4th/main.c
@@ -9,8 +9,34 @@
 #include "msp4th.h"
 
 
+
+/*
+ * Assumptions about clocking.  The affected register is the UART0_BCR.  See
+ * "ns430-uart.h" or the ns430 documentation for the relationship between BCR,
+ * the cpu clock rate, and the effective UART baud rate.
+ *
+ * A 12 MHz clock and a desired baudrate of 4800 yields a UARTx_CR value of 155
+ * from the UART_BCR() macro.
+ */
 #define DEVBOARD_CLOCK 12000000L
-#define BAUDRATE 19200L
+#define BAUDRATE 4800L
+
+
+/*
+ * Default msp4th settings
+ */
+#define MATH_STACK_SIZE 32
+#define ADDR_STACK_SIZE 64
+
+//total length of all user programs in opcodes
+#define USER_PROG_SIZE 256
+
+//max number of user-defined words
+#define USER_OPCODE_MAPPING_SIZE 32
+
+//total string length of all word names (+ 1x<space> each)
+#define USER_CMD_LIST_SIZE 128
+
 
 
 /*
@@ -74,23 +100,9 @@ void init_uart(void)
 
 
 /*
- * Default msp4th settings
- */
-#define MATH_STACK_SIZE 32
-#define ADDR_STACK_SIZE 64
-
-//total length of all user programs in opcodes
-#define USER_PROG_SIZE 256
-
-//max number of user-defined words
-#define USER_OPCODE_MAPPING_SIZE 32
-
-//total string length of all word names (+ 1x<space> each)
-#define USER_CMD_LIST_SIZE 128
-
-/*
- * The ".lastram" section should be placed so these vectors are the last part
+ * The ".noinit" section should be placed so these vectors are the last part
  * of allocated RAM.  All space beyond, up until 0xff00, is empty or unused.
+ * This keeps all the msp4th global variables in RAM in one continuous block.
  */
 int16_t __attribute__ ((section(".noinit"))) mathStackArray[MATH_STACK_SIZE];
 int16_t __attribute__ ((section(".noinit"))) addrStackArray[ADDR_STACK_SIZE];
@@ -150,6 +162,8 @@ int main(void){
      *  suffix Nf or Nb.
      */
 #ifdef BOOTROM
+    // set a flag to generate the code with the proper constants
+    // otherwise use the constants setup for testing
     asm(".set BOOTROM, 1");
 #endif
     asm(".include \"flashboot.s\"");
@@ -159,9 +173,15 @@ int main(void){
     init_uart();
 
     /*
-     * Startup and run msp4th interp
+     * Startup and run msp4th interp.
+     *
+     * See config_default_msp4th() and "test4th.c" for examples of
+     * re-configuring the program vector sizes and providing I/O functions.
      *
-     * word "exit" makes processLoop() return
+     * The following make processLoop() return:
+     *  - executing the "exit" word
+     *  - any EOT character in the input ('^D', control-D, 0x04)
+     *  - any 0xff character in the input
      */
     config_default_msp4th();
 
-- 
2.25.1