README.md

   1 #FastForth for MSP430FRxxxx TI's devices, light, fast, efficient, reliable.
   2
   3 Tested on TI MSP-EXP430FR(5739,5969,5994,6989,4133,2355,2433) launchpads, at 1, 2, 4, 8, 12, 16 MHz plus 20MHz & 24MHz with MSP430FR(23xx,57xx) devices.
   4
   5 It's an "interpret and compile" operating system for MSP430 devices with FRAM, very interesting because of its 5kB size.
   6
   7 That includes:
   8
   9 * the kernel FORTH with interpreting double numbers and Q15.16 numbers,
  10
  11 * an assembler with TI's syntax, "label free", with conditional compilation,
  12
  13 * a 16-input search engine that speeds up the interpreter by 4,
  14
  15 * an UART TERMINAL up to 6MBds, with software (XON/XOFF) + hardware (RTS) control flow,
  16
  17 * or an I2C TERMINAL up to 1MHz (overruns 2.5 times the TI specifications), see \MSP430-FORTH\UARTI2CS.f.
  18
  19 After downloading \MSP430-FORTH\ANS_COMP.f, FastForth becomes a true ANS FORTH for afficionados.
  20 Personally I use it mainly as super OS for real time programs.
  21
  22 If your goal is to learn or to teach programming with assembler, don't miss it, try it!
  23
  24 For only 3 kbytes in addition, you have the primitives to access the SD\_CARD FAT16 and FAT32: read, write, del, download source files and to copy them from PC to the SD_Card. It works with all SD\_CARD memories from 64MB to 64GB. The cycle of read/write a byte is below 1 us @ 16 MHz.
  25
  26 With all the kernel addons, including extended\_ASM and SD\_Card driver, FastForth size is 10 kB.
  27
  28 However, if all works well with Windows 10, it works less well with Linux due to the lack of a good alternative to TERATERM...
  29
  30 Note: for every update, download all subdirectories to correctly update the project, without missing configurations files.
  31
  32 ##how to connect TERMINAL
  33
  34     The files \binaries\launchpad_xMHz.txt are the executables ready to use with a serial terminal
  35     (TERATERM.exe), 115200Bds, with XON/XOFF or RTS_hardware flow controls and a PL2303TA/CP2102 cable.
  36     ------------------------------------------------------------------------------------------
  37     WARNING! doesn't use them to supply your launchpad: red wire is 5V ==> MSP430FRxxxx destroyed!
  38     ------------------------------------------------------------------------------------------
  39     (modify this first, by opening the box to weld red wire on 3.3V pad).
  40
  41 programming with MSP430Flasher.exe and FET interface
  42
  43      TI Launchpad <--> CP2102/PL2302TA cable <------> USB <-------------> TERATERM.exe
  44                RX <--- TX            )
  45               GND <--> GND           > used by FastForth TERMINAL
  46                TX ---> RX            )
  47               RTS ---> CTS (optionnal) RTS pin Px.y is described in your \inc\launchpad.asm)
  48
  49      TI Launchpad <--> FET interface  <-------------> USB <-------------> MSP430Flasher.exe
  50               Vcc <--- 3V3
  51        TST/SBWTCK <--> SBWTCK
  52               GND <--> GND
  53       RST/SBWTDIO <--> SBWTDIO
  54
  55 programming with BSL_Scripter.exe
  56
  57      TI Launchpad <--> CP2102/PL2303TA cable <------> USB <-------->+<--> TERATERM.exe
  58                RX <--- TX   )                                       |
  59               GND <--> GND  > used by FastForth TERMINAL            +<--> BSL_Scripter.exe
  60                TX ---> RX   )
  61               Vcc <--- 3V3      )
  62        TST/SBWTCK <--- RTS      )
  63               GND <--> GND      > used by BSL_Scripter
  64       RST/SBWTDIO <--> DTR      )
  65
  66     Before programming device, close teraterm TERMINAL and connect the wire RST/SBWTDIO <--> DTR
  67     Once device is programmed, open teraterm TERMINAL then disconnect the wire RST/SBWTDIO <--> DTR.
  68
  69 -
  70
  71     Once FastForth is loaded in the target FRAM memory, you add assembly code or FORTH code, or both,
  72     by downloading your source files which embedded FastForth and its assembler interpret and compile.
  73
  74     Beforehand, the preprocessor GEMA, by means of a \config\gema\target.pat file, will have translated
  75     your generic MSP430FR source file.f in a targeted MSP430FRxxxx source file.4th, allowing you to use
  76     symbolic addressing for all peripheral registers, without having to do declarations via FORTH words.
  77     A set of .bat files in \MSP430-FORTH folder is furnished to do all this automatically.
  78
  79     To see all specifications of FastForth, download \MSP430-FORTH\FF_SPECS.f.
  80
  81     To change the terminal baudrate on the fly, 9600 Bauds up to 6 MBds,
  82     download the file \MSP430-FORTH\CHNGBAUD.f.
  83     Beyond 1 MBds, shorten the PL2303HXD cable, down to 20 cm for 6MBds.
  84
  85     XON/XOFF flow control allows 3.75kV galvanic isolation of terminal input with SOIC8 Si8622EC|ISO7021.
  86     With powered SOIC16W ISOW7821, you have 5kV rms isolation for both XON/XOFF TERMINAL and a 3V3 75mA supply.
  87
  88     If you choose I2C_FastForth for your target, you will need of one more to make the USBtoI2C bridge.
  89
  90     After downloading of complementary words in \MSP430-FORTH\ANS_COMP.f, FastForth executes CORETEST.4th
  91     in less than a second, and without errors which ensures its compatibility with the FORTH CORE ANS94 standard.
  92
  93     Notice that FAST FORTH interprets lines up to 84 chars, only SPACE as delimiter, only CR+LF as
  94     End Of Line, and BACKSPACE.
  95     And that the high limit of FORTH program memory is $FF80.
  96
  97     Finally, using the SCITE editor as IDE, all is ready to do everything from its "tools" menu.
  98
  99 What is new ?
 100 -------------
 101
 102 V307
 103
 104     54 bytes added to (Kernel + Conditional_Compilation + Assembler).
 105
 106     Source file copy from I2C_TERMINAL to the SD_Card of any I2C_target works now.
 107
 108     The bootstrap call is modified: ' BOOT IS WARM          to start it,
 109                                     ' BOOT 2 + @ IS WARM    to stop it.
 110
 111     In addition of target's ID test made by Teraterm macro, a preamble has been added to all
 112     \MSP430-FORTH\source.f files to prohibit their downloading with another version of FastForth.
 113
 114     Words @ ! ALLOT come back from "ANS_COMP" add-on to core.
 115
 116     Recognized prefixes are $ # % and ' respectively for hex decimal binary and ASCII 'char' numbers.
 117     Examples: 'U' - $55 = 0, '3' - #33 = 0, '@' - %0100_0000 = 0.
 118     When use in source.f files, all ASCII special chars are available. See \inc\FastForthREGtoTI.pat.
 119
 120     Assembler allows "argument+offset" into FORTH area (0 to $FFFF).
 121     Examples: MOV #RXON,&SLEEP+2 to store RXON addr at SLEEP+2 addr.
 122               MOV.B BUFFER+-1(X),TOS to load the byte at BUFFER-1(X) addr in the register TOS.
 123
 124     COLD does same than hardware RST.
 125     WIPE does same than hardware SW1+RST (DEEP_RESET).
 126
 127
 128     More complicated:
 129
 130     In the FastForth init process, COLD WARM SLEEP are modified and INI_FORTH is added.
 131     They start each with an immediate call to a paired assembly subroutine:
 132
 133           RST_SYS failures ->+       +<- ABORT_TERM <- ABORT" <-(error)<-+-<-COMPILE/EXECUTE<-INTERPRET<-+
 134                              |       |                                   |                               ^
 135                              |       v                                   v                               |
 136           SW1+RST->+<-RST    |       +--> INI_FORTH -> ABORT" ->+->QUIT>-+->ACCEPT->+         +->ACCEPT->+
 137                    |         |            ---------             ^                   |         ^
 138                    v         v                                  |                   v         |
 139     words: WIPE -->+->COLD-->+-> RESET -> INI_FORTH --> WARM -->+                   +->SLEEP->+
 140                       ----                ---------     ----                           -----
 141
 142     subroutine:       COLD_APP            INI_SOFT_APP  INI_HARD_APP                   BACKGND_APP
 143     default CALL#     COLD_TERM           RET_ADR       INIT_TERM                      RXON
 144     Default action:   wait TERMINAL idle  do nothing    init TERM UCAx                 enable TERMINAL TX
 145                                                         + unlock I/O's                 (send RXON + /RTS)
 146
 147
 148     On the other hand, MARKER is modified in such a way that MARKER_DOES executes a CALL to
 149     the content of BODY+4, by default RET_ADR:
 150
 151     MARKER [CFA]    = DODOES
 152            [PFA]    = MARKER_DOES
 153            [BODY]   = previous DP (Dictionnary Pointer)
 154            [BODY+2] = previous VOCLINK (if word-set addon)
 155            [BODY+4] = RET_ADR
 156
 157     By replacing [BODY+4] with the address of a new defined subroutine (named for example: STOP_XXX),
 158     MARKER_DOES will execute it to restore all critical pointers saved at BODY+6, BODY+8...
 159
 160     Thus, with MARKER and the definition of subroutines COLD_XXX, INI_SOFT_XXX, INI_HARD_XXX, BACKGND_XXX
 161     the programmer has full control of his "XXX" real time application using interrupts,
 162     with everything he needs to start it, stop it, and also to properly remove it with
 163     a 'soft' MARKER word, avoiding the use of a WIPE or a SW1+RST of the last chance.
 164
 165     See examples in  /MSP430-FORTH/UARTI2CS.f,  /MSP430-FORTH/RTC.f.
 166
 167     notes: RST and SW1+RST (deep RST) are hardware redirected to COLD via NMI and the USER_NMI vector.
 168            INI_SOFT_SD is used as INI_SOFT_APP alias by the SD_CARD driver to reinit handles.
 169            WIPE|SW1+RST initialises this four APP calls plus TERMINAL_INT Vector.
 170
 171
 172 V306
 173
 174     8 bytes added to (Kernel + Conditional_Compilation + Assembler).
 175
 176     Fixed the crash caused by forgetting the prefix '&' in the last term of an assembly instruction.
 177     (the TI's symbolic mode is not implemented).
 178
 179     Added in the macro \config\SendFile.ttl the word ?ID to prevent any crash during download
 180     due to a device confusion:
 181         When downloading a source_file.f asked from the scite editor or by the use
 182         of SendSourceFileToTarget.bat, Teraterm macro first sends ?ID definition then
 183         the string:  %deviceID% ?ID.
 184         By executing ?ID, FastForth substracts %deviceID% value from the target's one then
 185         executes ABORT" DeviceID mismatch!" : the downloading is aborted if DeviceID mismatch.
 186         %deviceID% is provided by the file \config\select.bat.
 187
 188         When downloading a source_file.4TH, it's up to you to be careful because
 189         Teraterm sends the string 0 ?ID, so that ?ID bypasses the substraction.
 190         (when a source_file.4TH is issued from a source_file.f, you can verify
 191         the target name in its header).
 192
 193     Added the word set DOUBLE in the \MSP430-FORTH\DOUBLE.f file.
 194
 195 V305
 196
 197     -48 bytes.
 198
 199     from Scite menu, we can program MSP430FRxxxx also with BSL_Scripter.
 200
 201     To do, save file \prog\BSL_Scripter.exe from:
 202     https://github.com/drcrane/bslscripter-vs2017/releases/download/v3.4.2/BSL-Scripter-v3.4.2.zip,
 203     but erasing a MSP430FR2355 doesn't work.
 204
 205     and buy a USB2UART module CP2102 6 pin. On the web, search: "CP2102 3.3V DTR RTS"
 206     For wiring, see \config\BSL_Prog.bat.
 207
 208     So, we download both binaries and source files with only one CP2102|PL2303TA module,
 209     the XON/XOFF TERMINAL and BSL_Scripter. Bye bye T.I. FET!
 210
 211     ABORT messages display first the I2C address, if applicable.
 212     QNUMBER some issues solved.
 213     UART version of ACCEPT and KEY are shortened.
 214     EVALUATE is moved to CORE_ANS.
 215
 216 V304
 217
 218     -36 bytes.
 219
 220     for kernel compiling use the last version of srecord (1.64) to enable overlapping in vectors area.
 221
 222     The forthMSP430FR.lst output file is more readable because purged of all unused conditionnal parts.
 223
 224     Fixed: word F. issue in FIXPOINT.asm
 225
 226     Moved: words ALLOT and DOES> to CORE_ANS.asm/f files.
 227
 228     CORDIC.f also works without hardware MPY (MSP430FR4133).
 229
 230     By compiling :NONAME CODENNM DEFER IS, the new option DEFERRED superseeds the old NONAME option.
 231
 232     pin RESET is software replaced by pin NMI and so, RESET executes COLD, allowing code insert before BOR.
 233     however SYSRSTIV numbering remains unchanged: = 4 for RESET, = 6 for COLD.
 234
 235     Deep RESET reinitializes vectors interrupts and SIGNATURES area, as WIPE.
 236
 237     Fast Forth Deep RESET is done by switches S1 + RST.
 238
 239
 240     A newcomer: FastForth for I2C TERMINAL. With the driver UART2I2CS running on another FastForth target,
 241                 we have the USB to I2C_Slave bridge we need: one TERMINAL for up to 112 I2C_FastForth targets.
 242
 243                                                                                     +---------------------------+
 244       notebook                     USB to I2C_Slave bridge                    +-I2C-| others I2C_slave target   |
 245     +-----------+      +-------------------------------------------------+   /    +--------------------------+  |
 246     |           |      ¦ PL2303HXD         target running UARTI2CS @24MHz¦  +-I2C-|  MSP430FR4133 @ 1 MHz    |  |
 247     |           |      ¦------------+       +----------------------------¦ /   +--------------------------+  |--+
 248     |           |      ¦            | 3wires|   MSP430FR2355 @ 24MHz     ¦/    |   MSP430FR5738 @ 24 MHz  |  |
 249     | TERATERM -o->USB-o->USB2UART->o->UART-o-> FAST FORTH -> UARTI2CS  -o-I2C-o-> FAST FORTH with option |--+
 250     | terminal  |      ¦            | 6MBds |               (I2C MASTER) ¦     |  TERMINAL_I2C (I2C SLAVE)|
 251     |           |      ¦------------+       +----------------------------¦     +--------------------------+
 252     |           |      ¦            |< 20cm>|                            ¦       up to 112 I2C_Slave targets
 253     +-----------+      +-------------------------------------------------+
 254
 255     With the indicated MCLK and UART speeds, Coretest.4th is downloaded to (and executed by) I2C_Slave in 800ms.
 256     The driver UARTI2CS works without error from 1MHz up to 24MHz MCLK and from 115200Bds up to 6MBds UART.
 257     With I2C_Master running at 24 MHz, the I2C bus frequency is about 1MHz, and it works fine even if I2C_slave is running at 1 MHz.
 258     Don't forget to add two 3k3 pullup resistors on SCL and SDA...
 259
 260     the copy of a file to I2C target SD_Card doesn't work.
 261
 262     the Multi Master Mode works but is not tested in multi master environment.
 263
 264     "Cherry on the pudding", when they wait for a TERMINAL input (idle state),
 265     both I2C_Master and I2C_Slave(s) are sleeping in LPMx mode and the bus I2C is freed.
 266     Sleep modes down to LPM4 are available for I2C_Slave devices.
 267
 268     The driver UART2I2CS doesn't use the UCBx I2C_Master hardware, really too bad, but
 269     profitably its software version, much more faster, which consumes just two I/O (better in the range Px0-Px3),
 270     the UCBx remaining available for another I2C_Slave or SPI driver.
 271
 272     On the side of I2C_Slave, pins SDA SCL are those defined as BUS_TERM in the file \inc\your_target.asm.
 273     I2CSLA0, in the file forthMSP430FR.asm, defines the I2C_Slave address of the I2C FastForth module.
 274     for I2C_Master, see \inc\your_UARTI2CS_bridge.pat the correspondence of SM_SCL and SM_SDA.
 275
 276
 277 #####HOW TO DO ?
 278
 279     first you make a I2C cable (GND,SDA,SCL,3V3) between your 2 LaunchPad, with 3,3k pullup resistors on SDA and SCL lines.
 280     see each of two /inc/target.pat files to know SDA ans SCL pins.
 281
 282     to compile FastForth for I2C TERMINAL from forthMSP430FR.asm file:
 283     1-  uncomment the line "TERMINAL_I2C".
 284     2-  search "I2CSLAVEADR" line and set your <slave address you want>, i.e. 10h.
 285     3-  compile file then prog your I2C_Slave LaunchPad.
 286
 287     with the another LaunchPad running FastForth:
 288     At line 610 of UART2I2CS.f file set the <slave address you want>, i.e. $10.
 289     then download it, it's done: TERMINAL is linked to I2C_Slave.
 290
 291     Type `Alt+B` on teraterm (send UART break) to unlink I2C_Slave.
 292
 293 V302
 294
 295     -646 bytes
 296     Kernel + FIXPOINT input + DOUBLE input + :NONAME + Conditional Compilation + Assembler under 5 kB.
 297
 298     the FORTH kernel is drastically reduced to 55 words.
 299     All others are moved in the \ADDON\ANS_COMPLEMENT.asm file,
 300     the conditionnal compilation with the assembler allowing to reuse them on request.
 301
 302     Fixed:  QNUMBER,
 303             ACCEPT (XON/XOFF TERMINAL with MSP430FR2xxx).
 304     Modified: [ELSE].
 305
 306     FF_SPECS.f displays FastForth environment.
 307
 308 V301
 309
 310     -584 bytes, Kernel + Conditional Compilation + Assembler under 5.5 kb.
 311
 312     the FORTH kernel is drastically reduced to 82 words, just what the operating system needs.
 313     All others are moved in the \ADDON\ANS_COMPLEMENT.asm file, the conditionnal compilation
 314     allowing you to use them on request.
 315
 316     Taking into account the new TI launchpad LP_MSP430FR2476.
 317
 318     Fixed: :NONAME (now aligned), LOAD" (no more crash on error).
 319     Modified: ACCEPT, WORD, HEADER, CODE, ENDCODE, ASM, GOTO, ?GOTO, RPT.
 320     Removed JMP <word> and ?JMP <word> from assembler (replaced by GOTO BWx and ?GOTO BWx).
 321
 322     ACCEPT is modified to include the RXON call in the word SLEEP.
 323     By rewriting the defered word SLEEP, we can easily disable the TERMINAL_INPUT interrupt.
 324     See BACKGROUND, START and STOP  in \MSP430-FORTH\RC5toLCD.f.
 325
 326 V300
 327
 328     -4 bytes.
 329     The prompt "ok" becomes a compilation option.
 330
 331     Taking into account the digit separator '_' in ?NUMBER, to better see when typing binary numbers.
 332         example: %1010100011000111 can be typed as well: %1010_1000_1100_0111
 333
 334     Corrected >NUMBER
 335
 336     Modified GetFreeHandle CloseHandle
 337
 338     Tested with BLE 5.0 terminal (a couple of BGX13P EVK) at 16MHz, 921600 bds + terminal 5 wires:
 339         download throughput = 5 kbytes/s (and with errors when ECHO is ON), disappointing...
 340         (Bluetooth 2.1 terminal with one RN42 works well).
 341
 342     RePeaTed instructions RRUX,RRCX,RLAX,ADDX,SUBX work fine! See TESTASMX.4TH
 343
 344 V209
 345
 346     -26 bytes.
 347     V3 prerelease
 348     added experimental extended_assembler (MSP430FR5969,MSP430FR5994,MSP430FR6989)
 349
 350 V208
 351
 352     -58 bytes.
 353     Simplified directory structure of project.
 354     Added switch DOUBLE_INPUT as kernel compilation ADDON, removed switch LOWERCASE.
 355     Added \MSP430-FORTH\CORDIC.f for aficionados.
 356     Added FF_SPECS.4th to show all specificities of FastForth compilation.
 357     Corrected LITERAL (double LITERAL part).
 358     Modified ACCEPT COLD WARM ?ABORT, S", QNUMBER.
 359
 360 V207
 361
 362     -50 bytes.
 363     Unlocking I/O's is transfered from RESET to WARM.
 364     Thus, by redirecting WARM, you can add I/O's configuration of your application before unlock them.
 365
 366         two options to do this:
 367
 368             Light option:
 369             your START routine is inserted in WARM and continues with the default WARM.
 370             Search "START" in the \MSP430_FORTH\IR_RC5.f file as application example.
 371
 372             Complete option:
 373             START routine replaces WARM and continues with ABORT (without WARM message).
 374             In this case, you can also change the Reset events handling but you will need to unlock I/O's
 375             and configure TERMINAL I/O's in your START routine.
 376             Search "activate I/O" in \MSP430_FORTH\RC5toLCD.f file to see how to do.
 377
 378     Bugs corrected in target.asm, target.pat and device.inc files.
 379
 380 V206
 381
 382     The terminal baudrate can be changed on the fly. Download MSP430-FORTH\CHNGBAUD.f to do.
 383
 384     forthMSP430FR.asm:
 385
 386          Bugs corrected: ALSO and :NONAME (option).
 387
 388          The structure of primary DEFERred words as KEY,EMIT,CR,WARM... is modified,
 389                           -------
 390          the address of their default execute part, without name, can be found with:
 391          ' <name> >BODY
 392
 393              example, after this entry: ' DROP IS KEY
 394              KEY (or ' KEY EXECUTE) runs DROP i.e. runs the redirection made by IS,
 395              ' KEY >BODY EXECUTE runs KEY, the default action at the BODY address.
 396
 397              and: ' KEY >BODY IS KEY
 398              restore the default action of this primary DEFERred word.
 399                                                 -------
 400
 401         WARNING! you cannot do that with words created by DEFER !
 402         DEFER creates only secondary DEFERred words, without BODY !
 403                             ---------
 404
 405         to build a primary DEFERred FORTH word,
 406                     -------
 407         you must create a DEFERred word followed by a
 408         :NONAME definition, ended by ; IS <name>
 409
 410              DEFER truc
 411
 412              :NONAME         \ does nothing (for the example)
 413                  DUP
 414                  DROP
 415              ; IS truc
 416
 417         The advantage of creating primary DEFERred words is to set their
 418         default state, enabling to reinitialize them easily.
 419
 420     forthMSP430FR_ASM.asm:
 421
 422         All assembly code is revamped.
 423
 424         POPM and PUSHM instructions now follow the TI syntax :-(
 425
 426         Added CODENNM as assembly counterpart of :NONAME (option)
 427
 428         to build the primary DEFERred assembly word "machin" :
 429                      -------
 430
 431             DEFER machin
 432
 433             CODENNM
 434                 NOP2        \ assembly instruction
 435                 NOP3        \ assembly instruction
 436                 MOV @IP+,PC \ mandatory before ENDCODE
 437             ENDCODE IS machin
 438
 439         you can obviously mix LOW/HIGH levels in CODENNM and :NONAME areas...
 440
 441 V205
 442
 443     Added MSP-EXP430FR2355 launchpad
 444     Added word :NONAME (option).
 445     FastForth terminal via Bluetooth v2.1 + EDR (Microchip RN42) works fine in full duplex mode,
 446     up to 460800bds, 4 WIRES (GND,RX,TX,RTS); but with, as wireless effect, a bad troughput of 6kb/s
 447     instead of 30kb/s with a bridge UART2USB.
 448     Added 4Mbds,5Mbds terminal @16MHZ, for use with UART2USB PL2303HXD.
 449     Words AND, OR, XOR are moved as complement in ANS_COMP.f file.
 450     Simplified preprocessor files in \config\gema\ folder: only two for one target:
 451         one for the device, other for the target (launchpad or user application/module).
 452         and similarly with the assembly files: Device.inc and Target.asm, for compiling FastForth.
 453     Corrected startup time in target.asm files.
 454     Modified Clock config in MSP_EXP430FR2433.asm and MSP_EXP430FR4133.ASM, allowing clock modulation.
 455
 456 V202
 457
 458     added the line number in case of error occurring when download a source file (*f,*.4th)
 459     in HALFDUPLEX mode (scite command CTRL+2) or in default NOECHO mode (scite cmd CTRL+0).
 460     However, in case of download a file.f (with preprocessing), this line number refers
 461     to the contents of the file named LAST.4th.
 462
 463 V201
 464
 465     modified OPEN file primitive in forthMSP430FR_SD_LOAD.asm; modified forthMSP430FR_SD_INIT.asm
 466     reordered files preprocessor in only one folder.
 467
 468     You can now compile FastForth from Linux, see FastForth.pdf
 469     ...But desperately searching for the linux equivalent of TERATERM !
 470
 471     FastForth V2.0, major version.
 472
 473     Word TIB is deprecated and replaced by CIB (Current Input Buffer)
 474     Word CR generates CR+LF instead of CR. TYPE is rewritten in assembly.
 475
 476     Added fixed point s15q16 numbers. Thus FAST FORTH recognises :
 477     unsigned/signed numbers u/n (u <= 65535) / (-32768 <= n <= 32767),
 478     unsigned/signed double numbers ud/d by adding a decimal point
 479     (ud <= .4294967295) / (-.2147483648 <= d <= .2147483647),
 480     and s15q16 signed numbers by adding a comma (-32768,00000 <= s15q16 <= 32767,00000).
 481
 482     Fixed issue about the word LOAD": when called from a word, returns well into this calling word.
 483     Note that with MSP430FR57xx family, SDIB uses PAD, due to lack of RAM.
 484
 485     With the BOOTLOADER option, QUIT becomes a DEFERed word to easily enable/disable bootloader:
 486     ' BOOT IS WARM enables bootloader.
 487     WIPE disables bootloader.
 488
 489 V162
 490
 491     Added a set of words to enable conditional interpretation/compilation : MARKER [DEFINED] [UNDEFINED]
 492     [IF] [ELSE] [THEN]. A MARKER word (defined as {word} to well see it) allows you to wipe some program
 493     even if loaded in memory below RST_STATE boundary.
 494
 495     All interpretation/compilation errors now execute POWER_STATE, so any incorrect definition
 496     and all its source file will be automatically erased.
 497
 498     Added a bootloader option which loads BOOT.4TH from SD_Card memory.
 499
 500 V161
 501
 502     SD_Card driver works also with software multiplier (with MSP430FR4133)
 503     added SLEEP word enabling user access to background task,
 504     see ACCEPT in forthMSP430FR.asm and see use in RC5toLCD.f
 505
 506     You can type double numbers by inserting a decimal point.
 507     Example :   `$-12` is processed as 16 bits negative number.
 508                 `$-.12` or `$-1.2` or `$-12.` are processed as 32 bits negative numbers.
 509
 510     FAST FORTH V160, major version.
 511
 512     Accept SD_Card from 64 MB (FAT16) up to 64 GB (FAT32).
 513     Note that Windows 10 no longer offers the FAT32 format for the highest sizes of SD_CARD memory.
 514     So you must use an alternative to do, for example: https://www.partitionwizard.com.
 515
 516
 517     in SD_TOOLS the word SECTOR dumps a sector (use a 32 bits number).
 518                 the word CLUSTER dumps first sector of a cluster.
 519                 Usage (notice the point): number. CLUSTER or number. SECTOR
 520
 521     PREVIOUS versions
 522
 523     Added direct file transfer from PC to the target SD_CARD.
 524     Measured throughput with "HCI" SD CARD: 90 kbytes/s at 3Mbauds and 16MHz target clock.
 525     You can do it from scite editor (menu Tools) or by using specific bat file.
 526     Double click on it to see how to do.
 527
 528     JTAG and BSL signatures (FF80h-FF88h) are protected against overwrite, typically during
 529     source file download.
 530
 531     added signed number prefixes $ (hex), % (bin) and # (decimal) to supersede current BASE.
 532
 533     Added words ASM and ENDASM to create assembler words that are not interpretable by FORTH
 534     i.e. that are called by {CALL|INTERRUPT} and ended by {RET|RETI}. These so created words
 535     can be used only in ASSEMBLER context.
 536
 537     In the embedded assembler, added 3 backward BW1 BW2 BW3 and 3 forward FW1 FW2 FW3 jump labels
 538     to use with GOTO, ?GOTO.
 539     These labels are for single use (one jump for one label) but immediately reusable once resolved.
 540
 541     you can compile up to 32 threads vocabularies.
 542
 543     Memory management :
 544     Fast Forth defines 4 levels of program memory with this words :
 545         WIPE (and system failures) that resets program memory, vectors interrupts and any DEFERred words,
 546         RST_HERE/RST_STATE that sets/resets the boundary of program protected against <reset> and COLD,
 547         PWR_HERE/PWR_STATE that sets/resets the boundary of program protected against power ON/OFF,
 548         and nothing, i.e. volatile program.
 549
 550     You can download source files with hardware and/or software control flow (i.e. without line
 551     or char delays) up to:
 552         134400  bds @ 500kHz
 553         268800  bds @ 1MHz
 554         614400  bds @ 2MHz
 555         1228800 bds @ 4MHz
 556         2457600 bds @ 8MHz
 557         3000000 bds @ 16MHZ
 558         6000000 bds @ 24MHz with MSP430FR57xx devices
 559     See main file DTCforthMSP430FR5xxx.asm for the list of reliable baudrates.
 560
 561     FAST FORTH can be adjusted by selection of SWITCHES in the source file to reduce its size according
 562     to your convenience. To do, comment/uncomment their line.
 563
 564     for your application, select the mode LPM{0,1,2,3,4} that enables wake on FAST FORTH input,
 565     depending of family: FR2xxx: LPM0, FR57xx : LPM0 to LPM2, FR59xx : LPM0 to LPM4.
 566
 567     DEEP_RST (RESET + WIPE) can be hardware performed via the programmation interface
 568     (Vcc,RX,TX,RST,TEST,GND).
 569
 570 Many thanks to Brad Rodriguez
 571 -----------------------------
 572
 573 for his CamelForth which served me as a kind of canvas.
 574 And also to Matthias Koch for its ideas about Q15.16 implementation.
 575
 576 Unlike CamelForth FASTFORTH is a "Direct Threaded Code", with an embedded assembler following the standard syntax,
 577 not the one used in the world Forth.
 578
 579 Its core is fully compliant with the standard ANS.
 580
 581 It is optimized for the speed, especially in the interpreter mode, so that you can load an application program written in FORTH/Assembler faster than its binary via MSP430 Flasher.exe.
 582 Everything can be done from your text editor, the preprocessor and a serial terminal.
 583
 584 What's this and why?
 585 ---
 586
 587 I have first programmed atmel tiny devices.
 588 Particularly I2C master driver to have both I2C slave and I2C master on a ATtiny461.
 589 which means a lot of back and forth between the editor, assembler, the programmer and the test in situ.
 590
 591 Previously I had programmed a FORTH on a Motorola 6809 and had been seduced by the possibility of sending a source file directly to the target using a serial terminal. Target which compiled and executed the program. At the time FORTH program lay in a battery backed RAM.
 592
 593 The advent of chip MSP430 TEXAS INSTRUMENT with embedded FRAM gave me the idea to do it again : FAST FORTH was born.
 594
 595 Today I dropped the ATMEL chips and proprietary interfaces, I program my applications in a mix 80%/20% of assembler/FORTH I then sent on MSP430FR5738 chips with embedded FAST FORTH.
 596
 597 And that's the magic: After I finished editing (or modify) the source file, I press the "send" button in my text editor and I can test result on target in the second following. This is the whole point of an IDE reduced to its simplest form: a text editor, a cable, a target.
 598
 599 Content
 600 -------
 601
 602 See [FastForth.pdf](https://gitlab.com/Jean-Michel/FastForthForMSP430fr5xxx/-/blob/master/FastForth.pdf)
 603
 604 Organize your gitlab copy of FastForth
 605 -------
 606
 607 See [FastForth.pdf](https://gitlab.com/Jean-Michel/FastForthForMSP430fr5xxx/-/blob/master/FastForth.pdf)
 608
 609 Minimal Software
 610 -----
 611
 612 See [FastForth.pdf](https://gitlab.com/Jean-Michel/FastForthForMSP430fr5xxx/-/blob/master/FastForth.pdf)
 613
 614 Build the program file
 615 ----------------------
 616
 617 \forthMSP430FR.asm is the main file to compile FastForth:
 618
 619 Open forthMSP430FR.asm with scite editor
 620
 621 uncomment the target as you want, i.e. MSP_EXP430FR5969
 622
 623 choose frequency, baudrate, flow control.
 624
 625 uncomment options switches as your convenience.
 626
 627 save file.
 628
 629 assemble (CTRL+0). A window asks you for 4 parameters:
 630
 631 set target as first param, i.e. MSP_EXP430FR5969
 632
 633 then execute. the output will be \binaries\MSP_EXP430FR5969.txt
 634
 635 Load Txt file (TI format) to target
 636 -----------------------------------
 637
 638     in \binaries folder, drag your target.txt file and drop it on prog.bat
 639
 640     or use scite internal command TOOLS: FET prog (CTRL+1).
 641
 642 nota : programming the device use SBW2 interface, so UARTn is free for serial terminal connexion.
 643
 644 If you want to program your own MSP430FRxxxx board, wire its pins TST, RST, 3V3 and GND
 645 to same pins of the launchpad, on eZ-FET side of the programming connector.
 646
 647 Connect the FAST FORTH target to a serial terminal
 648 -------------------------------------------------
 649
 650 you will need an USBtoUART cable with a PL2303TA or PL2303HXD device that allows both XON/XOFF
 651 and hardware control flow :
 652
 653 [PL2303HXD 3.3V](http://www.google.com/search?q=PL2303HXD+3.3V+cable)
 654 [PL2303 driver](http://www.prolific.com.tw/US/ShowProduct.aspx?p_id=225&pcid=41)
 655
 656 WARNING! always verify VCC PIN = 3.3V before use to supply your target with.
 657
 658 or with a CP2102 device and 3.3V/5V that allows XON/XOFF control flow up to 921600 Bds:
 659
 660 [CP2102 3.3V](https://www.google.com/search?q=cp2102+3.3V+6PIN)
 661 [CP2102 driver](https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers)
 662
 663 WARNING! always verify VCC PIN = 3.3V before use to supply your target with.
 664
 665 or with a FT232RL device and 3.3V/5V but without XON/XOFF control flow:
 666
 667 [FT232RL 3.3V](http://www.google.com/search?q=FT232RL+3.3V)
 668 [FT232RL driver](https://www.ftdichip.com/Drivers/VCP.htm)
 669
 670 WARNING! always verify VCC PIN = 3.3V before use to supply your target with.
 671
 672 or compatible 921600bds wireless module: RN42 (bluesmirf), RN4878...
 673
 674 Send a source file.f or file.4th to the FAST FORH target
 675 ------------------
 676
 677 Three bat files are done in \MSP430-FORTH that enable you to do all you want.
 678 drag and drop your source file on to.
 679 you can also open any source file with scite editor, and do all you want via its Tools menu.
 680
 681 If you have any downloading error, first verify in "LAST.4th" that all lines are
 682 correctly ended with CR+LF.
 683
 684 SD_Card Load, Read, Write and Delete
 685 =============================================
 686
 687 First, hardware
 688 ---------------
 689
 690 If you have MSP-EXP430FR5994, nothing to do.
 691
 692 For the choice of a SD card socket be carefull, pin CD (Card Detect) must be present!
 693 google search: "micro SD card 9 pin"
 694 Look for the good wiring in /Launchpad.asm file
 695
 696 Compile with SD_Card addon
 697 --------------
 698
 699 in forthMSP430FR.asm, uncomment lines SD_CARD_LOADER,  SD_CARD_READ_WRITE, SD_TOOLS
 700 then compile for your target
 701
 702 the commands
 703 ------------
 704
 705 With the LOAD" pathame" command you load your source files from a SD_CARD memory in both execute
 706 and compile modes. Idem for READ", WRITE" and DEL" commands.
 707
 708 See "SD_TESTS.f", a FORTH program done for example
 709
 710 If you remove the SD memory card reader and then reset, all SD\_IO pins are available except SD_CD obviously.
 711
 712 HowTo LOAD a sourcefile
 713 --------------
 714
 715     LOAD" path\filename.4th".
 716
 717 The file is interpreted by FORTH in same manner than from the serial terminal.
 718
 719 When EOF is reached, the file is automatically closed.
 720
 721 A source file can _LOAD"_ an other source file, and so on in the limit of available handles (up to 8).
 722
 723 HowTo READ a file
 724 --------------
 725
 726     READ" path\filename.ext".
 727
 728 The first sector of this file is loaded in BUFFER.
 729 To read next sectors, use the command READ that loads the next sector in the buffer,
 730 and leaves on the stack a flag that is true when the EOF is reached.
 731 The file is automatically closed. See tstwords.4th for basic usage.
 732
 733 The variable BufferLen keep the count of bytes to be read (0 to 512).
 734
 735 If you want to anticipate the end, use the CLOSE command.
 736
 737 HowTo WRITE a file
 738 ---------------
 739
 740     WRITE" path\filename.ext".
 741
 742 If the file does not exist, create it, else open it and set the write pointer at the end of the file,
 743 ready to append chars.
 744
 745 See example of use in \MSP430-FORTH\SD_TEST.f.
 746
 747 To overwrite an existing file: DEL" file" then  WRITE" file".
 748
 749 Use CLOSE to close the file.
 750
 751 HowTo delete a file
 752 ---------------
 753
 754     DEL" path\filename.ext". If the file is not found, do nothing, no error.
 755
 756 HowTo change DIRectory
 757 ---------------
 758
 759     LOAD" \misc".             \misc becomes the current folder.
 760     LOAD" ..\"                parent folder becomes the current folder.
 761     LOAD" \"                Root becomes the current folder.
 762
 763 Drive letters are always ignored.
 764
 765 Downloading source file to SD_Card
 766 ------------------------------------------
 767
 768 to download a source file (.f or.4th) onto SD_CARD target, use CopySourceFileToTarget\_SD\_Card.bat.
 769 Double click on one of this bat files to see how to do.
 770
 771 or use scite.
 772
 773 If you have any downloading error, first verify in "LAST.4th" that all lines are
 774 correctly ended with CR+LF.
 775
 776 Other interesting specificities :
 777 =====
 778
 779 Management of vocabularies (not ANSI) with the option VOCABULARY_SET:
 780 VOCABULARY, DEFINITIONS, ONLY, ALSO, PREVIOUS, CONTEXT, CURRENT, FORTH, ASSEMBLER.
 781 In fact, it's the the assembler that requires the vocabularies management.
 782
 783 Recognizing prefixed numbers %101011 (bin), $00FE (hex) and #220 (decimal).
 784 you can insert underscores in numbers: %1100\_1101\_0000\_0001 instead of %1100110100000001.
 785
 786 ECHO / NOECHO
 787
 788 The words DEFER and IS are implemented. CR, EMIT, KEY, ACCEPT, QUIT and WARM are deferred words.
 789
 790 Error messages are colored (reverse video on ANSI terminal).
 791
 792 Assembly jumps are as FORTH one's : IF, ELSE, THEN, BEGIN, AGAIN, UNTIL, WHILE.
 793 Not canonical jumps are also available with GOTO|?GOTO to
 794 backward labels BW1 BW2 BW3 or forward labels FW1 FW2 FW3.
 795 Backward labels BWx are live until new definition, forward labels FWx are for single use.
 796 Switch  within definitions between FORTH and Assembly contexts with words HI2LO and LO2HI.
 797 See examples in the TstWords.f file. This is perhaps the most interesting feature for development...
 798
 799 The system is not responding ?
 800 ======
 801
 802 First, remove the USBtoUART bridge then reconnect it. Perhaps it was in suspend state...
 803
 804 If the system is always freezed, press <reset> button on the MSP-EXP430FR5xxx ; FORTH restarts
 805 as it was after the last RST_HERE command.
 806
 807 If the system does not restart again, press `SW1+RESET`.
 808 FORTH restarts in the state it is in its object txt file.
 809
 810 Here is the FastForth initialization process, in itself one of its major assets :
 811
 812     case 1 : when you type `PWR_STATE` ==> the program beyond PWR_HERE is lost.
 813
 814     case 1.1 : when you type `WARM`, FORTH interpreter is restarted, the program
 815                beyond of last PWR_HERE (or last RST_HERE) is lost.
 816                The WARM display is preceded by "#0".
 817
 818     case 1.2 : Power ON ==> performs a reset and the program beyond PWR_HERE is lost.
 819                the WARM display is preceded by the SYSRSTIV value "#2".
 820
 821     case 1.3 : SVSHIFG SVSH event ==> same effects,
 822                the WARM display is preceded by the SYSRSTIV decimal value "#14".
 823
 824
 825
 826     case 2 : when you type `RST_STATE` ==> the program beyond RST_HERE is lost.
 827
 828     case 2.1 : <RESET>  ==> performs reset and the program beyond RST_HERE is lost,
 829                the WARM display is preceded by the SYSRSTIV value "#4".
 830
 831     case 2.2 : when you type `COLD` (software reset) ==> same effects,
 832                the WARM display is preceded by the SYSRSTIV value "#6".
 833
 834     case 2.3 : PUC on failure ===> same effects,
 835                The WARM display is preceded by the SYSRSTIV decimal value.
 836
 837
 838
 839     case 3 : when you type `WIPE` ==> all programs donwloaded from the terminal or the SD_Card
 840              are lost, the default state of COLD_APP, INI_SOFT_APP, INI_HARD_APP and BACKGND_APP
 841              are restored, all "defered" words are initialised with their default value,
 842              same thing for interrupts vectors, and SIGNATURES area is cleared (FFh).
 843              The WARM display is preceded by #-1.
 844
 845     case 3.1 : <SW1+RESET> ==> performs deep reset, same effects.
 846                The WARM display is preceded by #-1.
 847
 848     case 3.2 : after compiling new FastForth ==> same effects, obviously!
 849                The WARM display is preceded by #-3.
 850
 851
 852     If you have previously set 'NOECHO', there is no WARM display.
 853
 854
 855     If an error occurs from the interpreter, FORTH is restarted,
 856     The error is always displayed and the program beyond PWR_HERE is lost.
 857
 858     In this way, any error is followed by the complete erasure of a bad definined word causing this error,
 859     or by that of the downloaded source file including it.
 860
 861     It is therefore recommended to end a source file with at least 'PWR_HERE' to protect it
 862     from any subsequent error.
 863
 864
 865 VOCABULARY ADD-ON
 866 ====
 867
 868 These words are not ANS94 compliant, they are those of F83 standard.
 869
 870 For example, after loading SD_TOOLS add-on, you can type: ALSO ASSEMBLER WORDS PREVIOUS WORDS
 871
 872     With ALSO ASSEMBLER, the vocabulary ASSEMBLER is added to the search CONTEXT thus the ASSEMBLER words
 873     become visible,
 874
 875     WORDS display the words of ASSEMBLER then those of FORTH,
 876
 877     PREVIOUS remove the vocabulary ASSEMBLER form the CONTEXT, and the ASSEMBLER words become hidden,
 878
 879     so the last WORDS display only FORTH words.
 880
 881 In the forthMSP430FR_ASM.asm, see the FORTH word CODE that add ASSEMBLER to the search CONTEXT and the ASSEMBLER word ENDCODE
 882  that remove ASSEMBLER from search CONTEXT. Thus, the assembler words can be used only between CODE and ENDCODE.
 883
 884 The CONTEXT can grow up to 6 vocabularies by using the word ALSO.
 885
 886 If you want add words to the assembler you must type: ALSO ASSEMBLER DEFINITIONS,
 887 The vocabulary ASSEMBLER is added to the search CONTEXT as previously but also becomes the CURRENT vocabulary in which the new words will be stored.
 888
 889 Finally, FORTH ONLY DEFINITIONS limits the search CONTEXT to FORTH and the CURRENT vocabulary is FORTH.
 890
 891 EMBEDDED ASSEMBLER
 892 ======
 893
 894 With the preprocessor GEMA the embedded assembler allows access to all system variables.
 895 See files \\inc\\Target.pat.
 896 You can also access to VARIABLE. See \\MSP430-FORTH\\TESTASM.4th.
 897
 898 HOW TO MIX assembly and FORTH ?
 899 ---
 900
 901 FAST FORTH knows three kinds of words :
 902
 903     high level FORTH words beginning with : <name> and ended with ;
 904
 905     low level assembly words starting with CODE <name> and ended with ENDCODE
 906
 907     low level assembly words starting with ASM <name> and ended by ENDASM
 908     these words are hidden because they are not FORTH executable.
 909     they can be used only by calling from CODE words.
 910
 911 Examples
 912
 913     : NOOP          \ FORTH word "NOOP", do nothing
 914         DUP
 915         DROP
 916     ;
 917
 918     CODE ADD        \ Assembly word "ADD", alias of word +
 919         ADD @PSP+,TOS
 920         MOV @IP+,PC
 921     ENDCODE
 922
 923     ASM WDT_INT     \ Watchdog interrupt
 924     BIT #8,&TERM_STATW  \ break (ALT+b) sent by TERMINAL ?
 925     0<> IF              \ if yes
 926         MOV #WARM,PC    \   continue with WARM
 927     THEN
 928     RETI                \ else return to background task SLEEP
 929     ENDASM
 930
 931
 932 To end a low level assembly word, the instruction MOV @IP+,PC jumps to the next FORTH word.
 933 This faster (4 cycles) and shorter (one word) instruction replaces the famous pair of assembly
 934 instructions : CALL #LABEL ... RET (4+4 cycles, 2+1 words). The register IP is the Interpretative Pointer.
 935
 936 High level FORTH word starts with a boot code DOCOL that save the IP pointer, load it with the first address
 937 of a list of execution addresses, then performs a postincrement branch to this first address.
 938 The list ends with the address of another piece of code EXIT (6 cycles) that restores IP before the instruction MOV @IP+,PC.
 939
 940 here, the compilation of low level word ADD :
 941
 942                     header          \ compiled by the word CODE
 943     execution addr  ADD @PSP+,TOS
 944                     MOV @IP+,PC     \ instruction called NEXT
 945
 946 and the one of the high level word NOOP :
 947
 948                     header          \ compiled by the word :
 949     execution addr  CALL rDOCOL     \ boot code compiled by the word :
 950                     addr of DUP     \ execution addr of DUP
 951                     addr of DROP    \ execution addr of DROP
 952                     addr of EXIT    \ execution addr of EXIT compiled by the word ;
 953
 954 _A high level FORTH word is a list of execution addresses preceded by a boot code and ending with EXIT address._
 955
 956 WRITING RULES
 957 --
 958
 959 any low level FORTH words must be ended with the instruction MOV @IP+,PC (NEXT).
 960
 961         CODE TEST               \ CODE starts a low level word
 962             asm1                \ assembly instruction 1
 963             asm2                \ assembly instruction 2
 964             MOV @IP+,PC         \ NEXT
 965         ENDCODE                 \ end of low level word
 966
 967 If you want to use the IP register, save it before and restore it before NEXT
 968
 969         CODE TEST1              \ CODE starts a low level word
 970             asm1                \ assembly instruction
 971             ...
 972             PUSH IP             \ save IP before use
 973             MOV #1,IP           \ assembly instruction that uses IP
 974             ...                 \ assembly instructions
 975             MOV @RSP+,IP        \ restore IP
 976             MOV @IP+,PC         \ NEXT
 977         ENDCODE                 \ end of low level word
 978
 979 A little more complex, the case of mixing FORTH and assembly with use of the words HI2LO, LO2HI and COLON
 980
 981         : MIX_FORTH_ASM         \ definition of a FORTH word starts with :
 982             SWAP
 983             DUP
 984         HI2LO                   \ FORTH to assembler switch
 985             asm1                \ you can freely use IP
 986             asm2
 987             ...
 988             ...
 989             MOV @RSP+,IP        \ restore IP stacked by :
 990             MOV @IP+,PC         \ NEXT
 991         ENDCODE                 \ end of low level word
 992
 993 If we see the code "MIX\_FORTH\_ASM" after compilation :
 994
 995             header              \ compiled by :
 996     exec@   CALL rDOCOL         \ boot code (which saves IP onto stack) compiled by :
 997             addr of SWAP
 998             addr of DUP
 999             next addr           \ addr of asm1, compiled by HI2LO
1000             asm1
1001             asm2
1002             ...
1003             ...
1004             MOV @RSP+,IP        \ restore IP saved by boot code
1005             MOV @IP+,PC         \ NEXT
1006
1007 going a step further :
1008
1009         CODE MIX_ASM_FORTH      \ CODE starts a low level word
1010             asm1
1011             asm2
1012         COLON                   \ starts high level
1013             word1
1014             word2
1015         ;                       \ end of high level word
1016
1017 If we see this code "MIX\_ASM\_FORTH" after compilation :
1018
1019             header              \ compiled by CODE
1020     exec@   asm1
1021             asm2
1022             CALL rDOCOL         \ compiled by COLON
1023             addr of word1
1024             addr of word2
1025             addr of EXIT        \ the word ; compiles address of EXIT that restores IP then executes MOV @IP+,PC
1026
1027 A new step
1028
1029         : MIX_FORTH_ASM_FORTH   \ definition of a FORTH word starts with :
1030             word1
1031             word2
1032             ...
1033         HI2LO                   \ FORTH to assembler switch
1034             MOV #0,IP           \ IP is free for use
1035             asm1
1036             ...
1037         LO2HI                   \ assembler to FORTH switch
1038             word3
1039             word4
1040         ;                       \ end of high level word
1041
1042 the compiled result
1043
1044             header              \ compiled by :
1045     exec@   CALL rDOCOL         \ boot code compiled by the word :
1046             addr of word1
1047             addr of word2
1048             ...
1049             next addr           \ compiled by HI2LO
1050             MOV #0,IP           \ IP is free for use
1051             asm1                \ assembly instruction
1052             ...
1053             CALL #EXIT          \ compiled by LO2HI (10 cycles switch)
1054             addr of word3
1055             addr of word4
1056             addr of EXIT
1057
1058 EXIT is used twice !
1059
1060 the first time, by LO2HI :
1061
1062     EXIT    MOV @RSP+,IP    \ 2 pop into IP the PC pushed on return stack by CALL #EXIT
1063             MOV @IP+,PC     \ 4 execute the routine at addr3
1064
1065 then at the end of FORTH word (addr5):
1066
1067     EXIT    MOV @RSP+,IP    \ 2 pop old IP from return stack
1068             MOV @IP+,PC     \ 4 execute the routine pointed by the old IP
1069
1070 Still another step :
1071
1072         CODE MIX_ASM_FORTH_ASM  \ CODE starts a low level word
1073             asm1
1074             asm2
1075         COLON                   \ switches from assembly to FORTH (COLON saves IP)
1076             word
1077             ...
1078         HI2LO                   \ FORTH to assembler switch
1079             asm3
1080             asm4
1081             MOV @RSP+,IP        \ restore IP
1082             MOV @IP+,PC         \ NEXT
1083         ENDCODE                 \ end of low level word
1084
1085 In fact, an exclusive of FAST FORTH, the start of a word FORTH can be placed anywhere :
1086
1087         CODE MIX_ASM_FORTH_ASM_FORTH
1088             asm1
1089             asm2
1090             ...
1091         COLON                   \ starts high level
1092             word1
1093             word2
1094             ...
1095         HI2LO                   \ FORTH to assembler switch
1096             asm3
1097             asm4
1098            ...
1099         LO2HI                   \ assembler to FORTH switch
1100             word
1101             word
1102             ...
1103         ;                       \ end of high level word
1104
1105 with the compiled result :
1106
1107             header              \ compiled by CODE
1108     exec@   asm
1109             asm
1110             CALL rDOCOL         \ compiled by COLON
1111             addr
1112             addr
1113             next address        \ compiled by HI2LO
1114             asm
1115             asm
1116             CALL #EXIT          \ compiled by LO2HI
1117             addr
1118             addr
1119             EXIT addr           \ that restores IP from return stack and then executes MOV @IP+,PC
1120
1121 As we see, IP is saved once time, it's logical.
1122
1123 ASSEMBLER WITHOUT LABELS ? YES !
1124 ---
1125
1126 To compare AS macro assembler and FastForth embedded assembler,
1127 compare files \ADDON\FIXPOINT.asm and \MSP430-FORTH\FIXPOINT.f
1128
1129 The conditionnal instructions doesn't use labels.
1130 Instead, they borrow FORTH's conditional environment:
1131
1132     CODE TEST_IF_THEN
1133         CMP #1,R8           \ set Z,N,V, flags
1134         0= IF               \ irritating, the "IF 0=" upside down, isn't it?
1135             ADD R8,R9       \ true part of comparaison
1136         THEN
1137         ...                 \ the next
1138         ...
1139         MOV @IP+,PC         \ don't forget...
1140     ENDCODE                 \ don't forget...
1141
1142 and the complete version :
1143
1144     CODE TEST_IF_ELSE_THEN
1145         CMP #1,R8           \ set Z,N,V, flags
1146         0= IF               \
1147             ADD R8,R9       \ true part of comparaison
1148         ELSE
1149             SUB R8,R9       \ false part of comparaison
1150         THEN
1151         ...                 \ the next for the two branches
1152         MOV @IP+,PC
1153     ENDCODE
1154
1155 test for loop back version BEGIN ... UNTIL
1156
1157     CODE TEST_BEGIN_UNTIL
1158         MOV #8,R10
1159         BEGIN
1160             SUB #1,R10      \ set Z,N,V flags
1161         0= UNTIL            \ loop back to BEGIN if flag Z is not set
1162         ...
1163         MOV @IP+,PC
1164     ENDCODE
1165
1166 test for out of loop version BEGIN ... WHILE ... REPEAT
1167
1168     CODE TEST_BEGIN_WHILE_REPEAT
1169         MOV #8,R10
1170         BEGIN
1171             SUB #1,R10      \ set Z,N,V flags
1172         0<> WHILE           \ go to out of loop if X=0 (Z flag =1)
1173             XOR #1,R9
1174         REPEAT              \ unconditionnal loop back to BEGIN
1175         ...                 \ out of loop here
1176         MOV @IP+,PC
1177     ENDCODE
1178
1179 infinite loop :
1180
1181     CODE TEST_BEGIN_AGAIN
1182         BEGIN
1183             ADD #1,R9
1184         AGAIN               \ unconditionnal loop back to BEGIN
1185     ENDCODE
1186
1187 to quit this infinite loop, press reset.
1188
1189 We can nest several conditional branches :
1190
1191     CODE TEST_NESTED_IF_ELSE
1192         CMP #0,R10
1193         0= IF
1194             CMP #0,R10
1195             0= IF
1196                 MOV #0,R11
1197             ELSE
1198                 SUB #1,R11
1199             THEN
1200         ELSE
1201             MOV #1,R11
1202         THEN
1203         MOV @IP+,PC
1204     ENDCODE
1205
1206 another nest :
1207
1208     CODE TEST_NESTED_BEGIN_AGAIN_IF
1209         MOV #8,R9
1210         BEGIN
1211             CMP #-1,R9
1212             0= IF
1213                 MOV @IP+,PC \ out of test_NESTED_BEGIN_AGAIN_IF
1214             THEN
1215             SUB #1,R9
1216         AGAIN
1217     ENDCODE
1218
1219 you can also MIX conditional branches with a mix of FORTH/assembly: see TEST5 in the demo file \MSP430-FORTH\TESTASM.4TH
1220
1221
1222 FAST FORTH have one pass assembler, not able to make forward jump.
1223
1224 I have added possibility of several "non canonical" jumps, up to 3 backward and up to 3 forward jumps to label :
1225
1226     \ C UM/MOD   udlo|udhi u1 -- ur uq
1227     CODE UM/MOD
1228         MOV @PSP+,W     \ 2 W = DIVIDENDhi
1229         MOV @PSP,S      \ 2 S = DIVIDENDlo
1230     \ T.I. ROUTINE  Section 5.1.5 of MSP430 Family Application Reports
1231         MOV #0,Y        \ 1 CLEAR RESULT
1232         MOV #16,X       \ 2 INITIALIZE LOOP COUNTER
1233     BW1 CMP TOS,W       \ 1
1234         U>= IF          \ 2
1235             SUB TOS,W   \ 1 if carry DIVIDENDhi-divisor
1236         THEN
1237     BEGIN
1238         ADDC Y,Y        \ 1 RLC quotient
1239         U>= ?GOTO FW1   \ 2 if carry Error: result > 16 bits
1240         SUB #1,X        \ 1 Decrement loop counter
1241         <0 ?GOTO FW2    \ 2 if 0< terminate w/o error
1242         ADD S,S         \ 1 RLA DIVIDENDlo
1243         ADDC W,W        \ 1 RLC DIVIDENDhi
1244         U< ?GOTO BW1    \ 2 if not carry    14~ loop
1245         SUB TOS,W       \ 1 if carry DIVIDENDhi-divisor
1246         BIS #1,SR       \ 1 SETC
1247     AGAIN               \ 2                 14~ loop
1248     FW2 BIC #1,SR       \ 1 CLRC  No error, C = 0
1249     FW1                 \  Error indication in C
1250     \ END of T.I. ROUTINE  Section 5.1.5 of MSP430 Family Application Reports
1251         MOV W,0(PSP)    \ 3 remainder on stack
1252         MOV Y,TOS       \ 1 quotient in TOS
1253         MOV @IP+,PC     \ 4
1254     ENDCODE
1255
1256 Forward labels FWx are for single use, backward labels BWx can solve several jumps,
1257 until new definition.
1258
1259 SYMBOLIC ASSEMBLER ? YES !
1260 --
1261
1262 I have discovered a little semantic preprocessor "GEMA", just like that FAST FORTH have its symbolic assembler !
1263
1264     \inc\DEVICE.pat contains memory map and vectors for a specified DEVICE
1265     \inc\LAUNCHPAD.pat is the I/O config file for specific LAUNCHPAD (or application)
1266
1267 gema translates also FORTH registers in ASM registers (R0 to R15)
1268
1269 With the three bat files in \MSP430_FORTH folder all is done automatically.
1270
1271 COMPILE FAST FORTH FOR YOUR MODULE
1272 --
1273
1274 1- in forthMSP430FR.asm "TARGET configuration"  create a line for your target, example:
1275
1276     ;MY_MSP430FR5738_1 ; compile for my own MSP430FR5738 miniboard V1
1277
1278 2- create your \inc\MSP430FR5738_1.asm and \inc\MSP430FR5738.inc from another target.asm and device.inc as pattern,
1279 Notice that you must define here only the necessary for FAST-FORTH compilation.
1280
1281 3- in \inc\ThingsInFirst.inc add one "device.inc" item:
1282
1283         .IFDEF MY_MSP430FR5738_1
1284     UCA0_UART   ; defines uart used by FORTH input terminal
1285     LF_XTAL     ; defines if your module have a 32768 Hz xtal, to enable it.
1286     UCB0_SD     ; defines UC used for SD Card driver if used
1287         .include "MSP430FR5738.inc"  ; include device declarations
1288         .ENDIF
1289
1290 4- in \inc\TargetInit.asm add one "target.asm" item:
1291
1292         .IFDEF MY_MSP430FR5738_1
1293             .include MY_MSP430FR5738_1.asm
1294         .ENDIF
1295
1296 Then, for the preprocessor which you will use when downloading source files:
1297
1298 1- create your \inc\device.pat file if not exist, from your \inc\device.inc and another \inc\device.pat as pattern.
1299
1300 2- create your \inc\target.pat file from your \inc\target.asm and another \inc\target.pat as pattern.
1301
1302 Best practice, I suggest you that all digital pins you define (input or output) in your projects have their idle state high, with external pull up resistor
1303 that is the reset state of FastForth...
1304
1305 START YOUR PROJECT
1306 --
1307
1308 How to start your project ?
1309
1310 I show you, assuming you are working from the scite editor with its enhanced tools menu.
1311
1312 First you create two files : project.f and test.f
1313
1314 PROJECT.f :
1315
1316     ; ----------------------------------------------------
1317     ; MSP_EXP430FR5969 16MHZ 4Mbds PROJECT.f
1318     ; ----------------------------------------------------
1319
1320     [DEFINED] {PROJECT} [IF] {PROJECT} [THEN] \ remove {PROJECT} if exist (memory managment)
1321
1322     MARKER {PROJECT}
1323
1324 here you append your already tested routines :
1325
1326     CODE FIRST  \ assembler CODE words are FORTH executable
1327         ...
1328     MOV @IP+,PC \ NEXT
1329     ENCODE
1330
1331     ASM TWO     \ assembler ASM words are not FORTH executable and can only be used in assembler mode
1332         ...     \ used to define interrupt routines, or subroutines called by CALL...
1333     RET         \ and ended by RET or RETI.
1334     ENDASM
1335
1336     CODE THREE
1337         ...
1338     CALL #TWO   \ CALL only ASM words
1339         ...
1340     MOV @IP+,PC \ NEXT
1341     ENCODE
1342
1343     ASM WDT_INT             \ interrupt routine
1344         ...
1345         ...
1346     BIC #WDTIFG,&SFRIFG1    \ reset WDT_INT flag
1347     BIC #$F8,0(RSP)         \ set CPU ON and GIE OFF in saved SR
1348     RETI                    \
1349     ENDASM
1350
1351     ;
1352
1353 then finish with this 2 "magic" words plus one optional : START, STOP and optional BACKGROUND
1354
1355     ASM BACKGROUND          \ (optional)
1356     BW1
1357         ...                 \ insert here your background task
1358         ...
1359         ...
1360     BIS &LPM_MODE,SR        \
1361     GOTO BW1
1362     ENDASM                  \
1363
1364
1365
1366
1367
1368     CODE START              \ to init your app
1369         ...                 \ init assembly part
1370     MOV #WDT_INT,&VEC_WDT   \ init WDT vector interrupt
1371         ...
1372     BIC #RC5,&P1REN         \ init I/O
1373         ...
1374
1375     MOV #SLEEP,X            \ redirect default background task
1376     MOV #BACKGROUND,2(X)    \ to yours (optional)
1377
1378     COLON
1379         ...                 \ init FORTH part
1380
1381         LIT RECURSE IS WARM \ replace WARM by START
1382         ['] WARM >BODY      \ and end START with default WARM
1383         EXECUTE             \ that unlock I/O, start FORTH process
1384     ;                       \ then fall down to sleep state, waiting any interrupt...
1385
1386
1387     CODE STOP               \ to properly stop your app
1388         MOV #SLEEP,X        \ restore the default background (optional)
1389         ADD #4,X            \ (word SLEEP can only be seen in assembler mode, not in FORTH)
1390         MOV X,-2(X)
1391     COLON
1392         ['] WARM >BODY
1393         IS WARM             \ remove START from FORTH init process
1394         ECHO                \ to always retrieve FORTH input terminal
1395         COLD                \ reset CPU, interrupt vectors and restart FORTH.
1396     ;
1397
1398
1399     RST_HERE
1400
1401     START       ; let's go!
1402
1403 end of file
1404
1405 Each time you download this project file, the word {PROJECT} removes all subsequent definitions,
1406 and the word RST_HERE protects the PROJECT against RESET.
1407
1408 The word START allows you to include your app init into FORTH's one.
1409 The word STOP unlink your app from FORTH init process.
1410
1411 Look at the file RC5toLCD.f to retrieve this structure.
1412
1413 TEST.f :
1414
1415     \ ----------------------------------
1416     \ MSP-EXP430FR5969_8MHZ_TEST.f
1417     \ ----------------------------------
1418
1419     RST_STATE   \ memory managment
1420
1421     here you write your routine to test
1422
1423     CODE TEST
1424     ...
1425     ...
1426     MOV @IP+,PC
1427     ENDCODE
1428
1429
1430     PWR_HERE    \ test.f content is protected against POWER OFF, but volatile with <reset>
1431
1432 Each time you download this TEST file, the word RST\_STATE clears memory content beyond PROJECT.
1433
1434 let's go
1435 --
1436
1437 With the SCITE menu tools : send a file.f, you download first your project.f file, then your test.f file that include the routine to test.
1438
1439 If the test don't work, modify it in the test.f file, then reload it.
1440
1441 When the routine "test" works as you want, you cut it in test.f file and copy it in project.f, then when you reload it, test is done !
1442
1443 Good luck !
1444
1445 ANNEXE
1446 ==
1447
1448 Here you have a good view of MSP430 assembly:
1449 [MSP430 ISA](http://www.ece.utep.edu/courses/web3376/Notes_files/ee3376-isa.pdf)
1450
1451 FastForth embedded assembler doesn't recognize the (useless) TI's symbolic addressing mode: ADD.B EDE,TONI.
1452
1453 REGISTERS correspondence (you can use freely ASM or TI or FASTFORTH registers's names).
1454
1455         ASSEMBLER   TI      FASTFORTH   comment
1456
1457         R0          PC      PC          Program Counter
1458         R1          SP      RSP         Return Stack Pointer
1459         R2          SR/CG1              Status Register/Constant Generator 1
1460         R3          CG2                 Constant Generator 2
1461         R4          R4      R (rDOCOL)  contents address of xDOCOL (DTC=1|2)
1462         R5          R5      Q (rDODOES) contents address of xdodoes
1463         R6          R6      P (rDOCON)  contents address of xdocon
1464         R7          R7      M (rDOVAR)  contents address of RFROM
1465         R8          R8      Y           scratch register
1466         R9          R9      X           scratch register
1467         R10         R10     W           scratch register
1468         R11         R11     T           scratch register
1469         R12         R12     S           scratch register
1470         R13         R13     IP          Interpretation Pointer
1471         R14         R14     TOS         Top Of parameters Stack
1472         R15         R15     PSP         Parameters Stack Pointer
1473
1474 **REGISTERS use**
1475
1476     The FASTFORTH registers rDOCOL, rDOVAR, rDOCON and rDODOES must be preserved.
1477     If you use them you can either PUSHM #4,M before and POPM #4,M after,
1478     or use then restore FastForth default values:
1479     xdocol, xdovar, xdocon, xdodoes. See device.pat.
1480
1481     But if you use this registers you must not at the same time call any FORTH words
1482     created by them!
1483
1484     don't use R3 and use R2 only with BIC, BIT, BIS instructions in register mode.
1485
1486     The bits 0-11 of SR register are saved by interrupts and restored by the instruction RETI.
1487     you can use freely UF9 UF10 and UF11 as SR bits 9-11.
1488     FastForth uses UF9 for double numbers interpreting.
1489
1490
1491 **PARAMETERS STACK**
1492
1493     The register TOS (Top Of Stack) is the first cell of the Parameters stack.
1494     The register PSP (Parameters Stack Pointer) points the second cell.
1495
1496     to push one cell on the PSP stack :
1497
1498         SUB #2,PSP                  \ insert a empty 2th cell
1499         MOV TOS,0(PSP)              \ fill this 2th cell with first cell
1500         MOV <what you want>,TOS     \ MOV or MOV.B <what you want>,TOS ; i.e. update first cell
1501
1502     to pop one cell from the PSP stack :
1503
1504         MOV @PSP+,TOS               \ first cell TOS is lost and replaced by the 2th.
1505
1506     don't never pop a byte with instruction MOV.B @PSP+, because it generates a stack misalignement...
1507
1508 **RETURN STACK**
1509
1510     register RSP is the Return Stack Pointer (SP).
1511
1512     to push one cell on the RSP stack :
1513
1514         PUSH <what you want>        \
1515
1516     to pop one cell from the RSP stack :
1517
1518         MOV @RSP+,<where you want>   \
1519
1520     don't never pop a byte with instruction MOV.B @RSP+, ...
1521
1522
1523     to push multiple registers on the RSP stack :
1524
1525         PUSHM #n,Rx                 \  with 0 <= x-(n-1) < 16
1526
1527     to pop multiple registers from the RSP stack :
1528
1529         POPM #n,Rx                  \  with 0 <= x-(n-1) < 16
1530
1531     PUSHM order : PSP,TOS, IP, S , T , W , X , Y ,rDOVAR,rDOCON,rDODOES,rDOCOL, R3, SR,RSP, PC
1532     PUSHM order : R15,R14,R13,R12,R11,R10, R9, R8,  R7  ,  R6  ,  R5   ,  R4  , R3, R2, R1, R0
1533
1534     example : PUSHM #6,IP pushes IP,S,T,W,X,Y registers to return stack
1535
1536     POPM  order :  PC,RSP, SR, R3,rDOCOL,rDODOES,rDOCON,rDOVAR, Y , X , W , T , S , IP,TOS,PSP
1537     POPM  order :  R0, R1, R2, R3,  R4  ,  R5   ,  R6  ,   R7 , R8, R9,R10,R11,R12,R13,R14,R15
1538
1539     example : POPM #6,IP pulls Y,X,W,T,S,IP registers from return stack
1540
1541     error occurs if n is out of bounds
1542
1543 **conditionnal jumps use**
1544
1545     0=    with IF UNTIL WHILE ?GOTO
1546     0<>   with IF UNTIL WHILE ?GOTO
1547     U>=   with IF UNTIL WHILE ?GOTO
1548     U<    with IF UNTIL WHILE ?GOTO
1549     S<    with IF UNTIL WHILE ?GOTO
1550     S>=   with IF UNTIL WHILE ?GOTO
1551     0>=   with IF UNTIL WHILE
1552     0<    with ?GOTO