README.md

   1 FastForth for MSP430FRxxxxTI's chips, from 16k FRAM
   2 ==================================================
   3
   4 Tested on all MSP-EXP430FRxxxx TI launchpads (5739,5969,5994,6989,4133,2355,2433) and CHIPSTICKFR2433, at 0.5, 1, 2, 4, 8, 12, 16 MHz plus 20MHz and 24MHz with FR23xx,FR57xx devices.
   5
   6 Fast Forth is a fast and well-made embedded interpreter/assembler/compiler, very interesting because of its size of 6 KB.
   7 This includes the FORTH language, a symbolic assembler without labels, conditional compilation, a 16-input search engine which
   8 speeds up the Forth interpreter by a factor of 4 and a connection to the serial terminal (TERATERM.exe), with 3 wires software flow control (XON/XOFF) and/or 4 wires hardware control flow, up to 6 Mbds.
   9 If your goal is to program a MSP430FRxxxx in assembler, FAST FORTH is the Swiss Army knife you absolutely need!
  10
  11 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.
  12 It works with all SD\_CARD memories from 64MB to 64GB. The cycle of read/write byte is below 1 us @ 16 MHz.
  13 This enables to make a fast data logger with a small footprint as a MSP430FR5738 QFN24.
  14
  15 With all kernel options FastForth size is under 10kB.
  16
  17     The files launchpad_xMHz.txt are the executables ready to use with
  18     a PL2303HXD cable and a serial terminal (TERATERM.exe) at 115200Bds with XON/XOFF,
  19     or RTS hardware flow control
  20     ------------------------------------------------------------------------------------------
  21     WARNING! don't use it to supply your launchpad: red wire is 5V ==> MSP430FRxxxx destroyed!
  22     ------------------------------------------------------------------------------------------
  23     (you can modify this by opening the box and by welding red wire on 3.3V pad).
  24
  25      TI Launchpad      PL2302HXD cable
  26                RX <--- TX
  27                TX ---> RX
  28               GND <--> GND
  29               RTS ---> CTS (not necessary if software XON/XOFF flow control
  30                             see in your launchpad.asm to find RTS pin).
  31
  32     The interest of XON/XOFF flow control is to allow 3.75kV galvanic isolation of terminal input
  33     with SOIC8 Si8622EC, or better yet, powered 5kV galvanic isolation with SOIC16 ISOW7821.
  34
  35     If you want to change the terminal baudrate on the fly (230400 bds up to 6 Mbds),
  36     download to your launchpad the file \MSP430-FORTH\CHNGBAUD.4th.
  37
  38     To see all compilation options, download \MSP430-FORTH\FastForthSpecs.4th
  39
  40     Once the Fast Forth kernel is loaded in the target FRAM memory, you add assembly code or
  41     FORTH code, or both, by downloading your source files that the embedded FastForth interprets and
  42     compiles.
  43     Beforehand, the preprocessor GEMA, by means of a \config\gema\target.pat file, will have translated
  44     the generic source file.f in a targeted source file.4th. This allows the assembler to use
  45     symbolic addresses for all peripheral registers without having to declare them in the embedded FORTH.
  46     A set of .bat files in \MSP430-FORTH folder is furnished to do this automatically.
  47
  48     The download, interpretation and compilation of a source_file.4th (without comments) is done
  49     at a throughput up to 40/80/120 kbytes/sec with a 8/16/24 MHz clock.
  50     Considering a ratio 4/1, that of the compiled code is 10/20/30 kbytes/sec.
  51
  52     After downloading of complementary words in \MSP430-FORTH\ANS_COMP.f, FastForth executes CORETEST.4th
  53     without errors which ensures its compatibility with the FORTH CORE ANS94 standard.
  54
  55     Notice that FAST FORTH interprets lines up to 84 chars, only SPACE as delimiter, only CR+LF as
  56     End Of Line, and BACKSPACE.
  57     And that the high limit of program memory is $FF80.
  58
  59     Finally, using the SCITE editor as IDE, all is ready to do everything from its "tools" menu.
  60
  61 What is new ?
  62 -------------
  63
  64 V208
  65
  66     -52 bytes.
  67     Added switch DOUBLE_INPUT as kernel compilation ADDON, removed switch LOWERCASE.
  68     Added \MSP430-FORTH\CORDIC.f for aficionados.
  69     Added FastForthSpecs.4th which shows all specs of FastForth.
  70     Corrected LITERAL (double LITERAL part).
  71     Modified ACCEPT COLD WARM ?ABORT, S".
  72
  73 V207
  74
  75     -50 bytes.
  76     Unlocking I/O's is transfered from RESET to WARM.
  77     Thus, by redirecting WARM, you can add I/O's configuration of your application before unlock them.
  78
  79         two options to do this:
  80
  81             Light option:
  82             your START routine is inserted in WARM and continues with the default WARM.
  83             Search "START" in the \MSP430_FORTH\IR_RC5.f file as application example.
  84
  85             Complete option:
  86             START routine replaces WARM and continues with ABORT (without WARM message).
  87             In this case, you can also change the Reset events handling but you will need to unlock I/O's
  88             and configure TERMINAL I/O's in your START routine.
  89             Search "activate I/O" in \MSP430_FORTH\RC5toLCD.f file to see how to do.
  90
  91     Bugs corrected in target.asm, target.pat and device.inc files.
  92
  93 V206
  94
  95     The terminal baudrate can be changed on the fly. Download MSP430-FORTH\CHNGBAUD.f to test.
  96
  97     forthMSP430FR.asm:
  98
  99          Bugs corrected: ALSO and :NONAME (option).
 100
 101          The structure of primary DEFERred words as KEY,EMIT,CR,WARM... is modified,
 102                           -------
 103          the address of their default execute part, without name, can be found with:
 104          ' <name> >BODY
 105
 106              example, after this entry: ' DROP IS KEY
 107              KEY (or ' KEY EXECUTE) runs DROP i.e. runs the redirection made by IS,
 108              ' KEY >BODY EXECUTE runs KEY, the default action at the BODY address.
 109
 110              and: ' KEY >BODY IS KEY
 111              restore the default action of this primary DEFERred word.
 112                                                 -------
 113
 114         WARNING! you cannot do that with words created by DEFER !
 115         DEFER creates only secondary DEFERred words, without BODY !
 116                             ---------
 117
 118         to build a primary DEFERred FORTH word,
 119                     -------
 120         you must create a DEFERred word followed by a
 121         :NONAME definition, ended by ; IS <name>
 122
 123              DEFER truc
 124
 125              :NONAME         \ does nothing (for the example)
 126                  DUP
 127                  DROP
 128              ; IS truc
 129
 130         The advantage of creating primary DEFERred words is to set their
 131         default state, enabling to reinitialize them easily.
 132
 133     forthMSP430FR_ASM.asm:
 134
 135         All assembly code is revamped.
 136
 137         POPM and PUSHM instructions now follow the TI syntax :-(
 138
 139         Added CODENNM as assembly counterpart of :NONAME (option)
 140
 141         to build the primary DEFERred assembly word "machin" :
 142                      -------
 143
 144             DEFER machin
 145
 146             CODENNM
 147                 NOP2        \ assembly instruction
 148                 NOP3        \ assembly instruction
 149                 MOV @IP+,PC \ mandatory before ENDCODE
 150             ENDCODE IS machin
 151
 152         you can obviously mix LOW/HIGH levels in CODENNM and :NONAME areas...
 153
 154 V205
 155
 156     Added MSP-EXP430FR2355 launchpad
 157     Added word :NONAME (option).
 158     FastForth terminal via Bluetooth v2.1 + EDR (Microchip RN42) works fine in full duplex mode,
 159     up to 460800bds, 4 WIRES (GND,RX,TX,RTS); but with, as wireless effect, a bad troughput of 6kb/s
 160     instead of 30kb/s with a bridge UART2USB.
 161     Added 4Mbds,5Mbds terminal @16MHZ, for use with UART2USB PL2303HXD.
 162     Words AND, OR, XOR are moved as complement in ANS_COMP.f file.
 163     Simplified preprocessor files in \config\gema\ folder: only two for one target:
 164         one for the device, other for the target (launchpad or user application/module).
 165         and similarly with the assembly files: Device.inc and Target.asm, for compiling FastForth.
 166     Corrected startup time in target.asm files.
 167     Modified Clock config in MSP_EXP430FR2433.asm and MSP_EXP430FR4133.ASM, allowing clock modulation.
 168
 169 V202
 170
 171     added the line number in case of error occurring when download a source file (*f,*.4th)
 172     in HALFDUPLEX mode (scite command CTRL+2) or in default NOECHO mode (scite cmd CTRL+0).
 173     However, in case of download a file.f (with preprocessing), this line number refers
 174     to the contents of the file named LAST.4th.
 175
 176 V201
 177
 178     modified OPEN file primitive in forthMSP430FR_SD_LOAD.asm; modified forthMSP430FR_SD_INIT.asm
 179     reordered files preprocessor in only one folder.
 180
 181     You can now compile FastForth from Linux, see FastForth.pdf
 182     ...But desperately searching for the linux equivalent of TERATERM !
 183
 184     FastForth V2.0, major version.
 185
 186     Word TIB is deprecated and replaced by CIB (Current Input Buffer)
 187     Word CR generates CR+LF instead of CR. TYPE is rewritten in assembly.
 188
 189     Added fixed point s15q16 numbers. Thus FAST FORTH recognises :
 190     unsigned/signed numbers u/n (u <= 65535) / (-32768 <= n <= 32767),
 191     unsigned/signed double numbers ud/d by adding a decimal point
 192     (ud <= .4294967295) / (-.2147483648 <= d <= .2147483647),
 193     and s15q16 signed numbers by adding a comma (-32768,00000 <= s15q16 <= 32767,00000).
 194
 195     Fixed issue about the word LOAD": when called from a word, returns well into this calling word.
 196     Note that with MSP430FR57xx family, SDIB uses PAD, due to lack of RAM.
 197
 198     With the BOOTLOADER option, QUIT becomes a DEFERed word to easily enable/disable bootloader:
 199     ' BOOT IS QUIT enables bootloader.
 200     ' QUIT >BODY IS QUIT disables bootloader.
 201
 202     Added QUIETBOOT option to enable BOOT without displaying; use with care...
 203
 204 V162
 205
 206     Added a set of words to enable conditional interpretation/compilation : MARKER [DEFINED] [UNDEFINED]
 207     [IF] [ELSE] [THEN]. A MARKER word (defined as {word} to well see it) allows you to wipe some program
 208     even if loaded in memory below RST_STATE boundary. See conditional compilation source files
 209     in \MSP430-FORTH.
 210
 211     All interpretation/compilation errors now execute POWER_STATE, so any incorrect definition
 212     and all its source file will be automatically erased.
 213
 214     Added a bootloader option which loads BOOT.4TH from SD_Card memory.
 215
 216 V161
 217
 218     SD_Card driver works also with software multiplier (with MSP430FR4133)
 219     added SLEEP and (SLEEP) words enabling user access to background task,
 220     see ACCEPT in forthMSP430FR.asm and see use in RC5toLCD.f
 221
 222     You can type double numbers by inserting a decimal point.
 223     Example :   $-12 is processed as 16 bits negative number.
 224                 $-.12 or $-1.2 or $-12. are processed as 32 bits negative numbers.
 225
 226         FAST FORTH V160, major version.
 227
 228     Accept SD_Card from 64 MB (FAT16) up to 64 GB (FAT32).
 229     Note that Windows 10 no longer offers the FAT32 format for the highest sizes of SD_CARD memory.
 230     So you must use an alternative to do, for example: https://www.partitionwizard.com.
 231
 232
 233     in SD_TOOLS the word SECT_D (dump sector) use a 32 bits number.
 234                 added the word CLUST_D (dump first sector of a cluster).
 235                 Usage (notice the point): number. CLUST_D
 236
 237     PREVIOUS versions
 238
 239     Added direct file transfer from PC to the target SD_CARD.
 240     Measured throughput with "HCI" SD CARD: 90 kbytes/s at 3Mbauds and 16MHz target clock.
 241     You can do it from scite editor (menu Tools) or by using specific bat file.
 242     Double click on it to see how to do.
 243
 244     JTAG and BSL signatures (FF80h-FF88h) are protected against overwrite, typically during
 245     source file download.
 246
 247     added signed number prefixes $ (hex), % (bin) and # (decimal) to supersede current BASE.
 248
 249         Added words ASM and ENDASM to create assembler words that are not interpretable by FORTH
 250     i.e. that are called by {CALL|INTERRUPT} and ended by {RET|RETI}. These so created words
 251     can be used only in ASSEMBLER context.
 252
 253         In the embedded assembler, added 3 backward BW1 BW2 BW3 and 3 forward FW1 FW2 FW3 jump labels
 254     to use with GOTO, ?GOTO.
 255     These labels are for single use (one jump for one label) but immediately reusable once resolved.
 256
 257         you can compile up to 32 threads vocabularies.
 258
 259         Memory management :
 260         Fast Forth defines 4 levels of program memory with this words :
 261                 WIPE (and system failures) that resets program memory, vectors interrupts and any DEFERred words,
 262                 RST_HERE/RST_STATE that sets/resets the boundary of program protected against <reset> and COLD,
 263                 PWR_HERE/PWR_STATE that sets/resets the boundary of program protected against power ON/OFF,
 264                 and nothing, i.e. volatile program.
 265
 266         You can download source files with hardware and/or software control flow (i.e. without line
 267     or char delays) up to:
 268                 134400  bds @ 500kHz
 269         268800  bds @ 1MHz
 270         614400  bds @ 2MHz
 271         1228800 bds @ 4MHz
 272         2457600 bds @ 8MHz
 273         3000000 bds @ 16MHZ
 274         6000000 bds @ 24MHz with MSP430FR57xx devices
 275     See main file DTCforthMSP430FR5xxx.asm for the list of reliable baudrates.
 276
 277         FAST FORTH can be adjusted by selection of SWITCHES in the source file to reduce its size according
 278         to your convenience. To do, comment/uncomment their line.
 279
 280     for your application, select the mode LPM{0,1,2,3,4} that enables wake on FAST FORTH input,
 281     depending of family: FR2xxx: LPM0, FR57xx : LPM0 to LPM2, FR59xx : LPM0 to LPM4.
 282
 283     DEEP_RST (RESET + WIPE) can be hardware performed via the programmation interface
 284     (Vcc,RX,TX,RST,TEST,GND).
 285
 286
 287 Many thanks to Brad Rodriguez
 288 -----------------------------
 289
 290 for his CamelForth which served me as a kind of canvas.
 291 And also to Matthias Koch for its ideas about s15.16 implementation.
 292
 293 Unlike CamelForth this FORTH is a "Direct Threaded Code", with an embedded assembler following the standard syntax,
 294 not the one used in the world Forth.
 295
 296 Its core is fully compliant with the standard ANS.
 297
 298 This is a FORTH 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 : everything can be done from your text editor, the preprocessor and a serial terminal.
 299
 300 What's this and why?
 301 ---
 302
 303 I have first programmed atmel tiny devices.
 304 Particularly I2C master driver to have both I2C slave and I2C master on a ATtiny461.
 305 which means a lot of back and forth between the editor, assembler, the programmer and the test in situ.
 306
 307 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.
 308
 309 The advent of chip MSP430 TEXAS INSTRUMENT with embedded FRAM gave me the idea to do it again : FAST FORTH was born.
 310
 311 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.
 312
 313 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.
 314
 315
 316 Content
 317 -------
 318
 319 With a size of about 6 kb, Fast Forth contains 115 words:
 320
 321     ASM            CODE           HI2LO          COLD           WARM           (WARM)         WIPE
 322     RST_HERE       PWR_HERE       RST_STATE      PWR_STATE      MOVE           LEAVE          +LOOP
 323     LOOP           DO             REPEAT         WHILE          AGAIN          UNTIL          BEGIN
 324     THEN           ELSE           IF             ;              :              DEFER          DOES>
 325     CREATE         CONSTANT       VARIABLE       POSTPONE       RECURSE        IMMEDIATE      IS
 326     [']            ]              [              \              '              ABORT"         ABORT
 327     QUIT           EVALUATE       COUNT          LITERAL        ,              EXECUTE        >NUMBER
 328     FIND           WORD           ."             S"             TYPE           SPACES         SPACE
 329     CR             (CR)           NOECHO         ECHO           EMIT           (EMIT)         ACCEPT
 330     KEY            (KEY)          C,             ALLOT          HERE           .              D.
 331     U.             SIGN           HOLD           #>             #S             #              <#
 332     BL             STATE          BASE           CIB            J              I              UNLOOP
 333     U<             >              <              =              0>             0<             0=
 334     DABS           ABS            NEGATE         1-             1+             -              +
 335     C!             C@             !              @              DEPTH          R@             R>
 336     >R             ROT            OVER           SWAP           NIP            DROP           ?DUP
 337     DUP            LIT            EXIT
 338
 339 ...size that includes its embedded assembler of 71 words:
 340
 341     ?GOTO          GOTO           FW3            FW2            FW1            BW3            BW2
 342     BW1            ?JMP           JMP            REPEAT         WHILE          AGAIN          UNTIL
 343     ELSE           THEN           IF             0=             0<>            U>=            U<
 344     0<             0>=            S<             S>=            RRUM           RLAM           RRAM
 345     RRCM           POPM           PUSHM          CALL           PUSH.B         PUSH           SXT
 346     RRA.B          RRA            SWPB           RRC.B          RRC            AND.B          AND
 347     XOR.B          XOR            BIS.B          BIS            BIC.B          BIC            BIT.B
 348     BIT            DADD.B         DADD           CMP.B          CMP            SUB.B          SUB
 349     SUBC.B         SUBC           ADDC.B         ADDC           ADD.B          ADD            MOV.B
 350     MOV            RETI           LO2HI          COLON          ENDASM         ENDCODE        (SLEEP)
 351     SLEEP
 352
 353 ...everything you need to program effectively in assembly or FORTH or mix, as you want.
 354 See examples in \MSP430-FORTH.
 355
 356
 357 Here are kernel compilation options:
 358
 359 CONDCOMP which enable conditional compilation:
 360
 361     [DEFINED]      [UNDEFINED]    [IF]           [ELSE]         [THEN]         COMPARE        MARKER
 362
 363 SD\_CARD\_LOADER to load FORTH source files from SD_CARD
 364
 365     LOAD"         (ACCEPT)
 366
 367 SD\_CARD\_READ\_WRITE to read write delete files and direct copy from TERMinal input to SD_card
 368
 369     TERM2SD"       SD_EMIT        WRITE          WRITE"         READ           READ"          CLOSE
 370     DEL"
 371
 372 BOOTLOADER adds a boot on SD_CARD
 373
 374     (QUIT)         BOOT
 375
 376 VOCABULARY to create vocabularies (words list)
 377
 378     DEFINITIONS    ONLY           PREVIOUS       ALSO           FORTH          VOCABULARY
 379
 380
 381
 382 ADDs-ON below may be added either hard in kernel or later loaded/removed as any application:
 383
 384 ANS\_CORE\_COMPLIANT necessary to pass ANS94 CORE tests
 385
 386     PAD            >IN            >BODY          SOURCE         .(             (              DECIMAL
 387     HEX            FILL           +!             [CHAR]         CHAR           CELL+          CELLS
 388     CHAR+          CHARS          ALIGN          ALIGNED        2OVER          2SWAP          2DROP
 389     2DUP           2!             2@             */             */MOD          MOD            /
 390     /MOD           *              FM/MOD         SM/REM         UM/MOD         M*             UM*
 391     S>D            2/             2*             MIN            MAX            RSHIFT         LSHIFT
 392     INVERT         AND            OR             XOR            {ANS_COMP}
 393
 394 SD\_TOOLS, basic tools for FAT16/32
 395
 396     DIR            FAT            CLUSTER        SECTOR         {SD_TOOLS}
 397
 398 FIXPOINT, minimalist fixed point arithmetic + - * /
 399
 400     2CONSTANT      D>F            S>F            F.             F*             F#S            F/
 401     F-             F+             HOLDS          {FIXPOINT}
 402
 403 UTILITY:
 404
 405     DUMP           U.R            WORDS          ?              .RS            .S             {UTILITY}
 406
 407
 408
 409
 410 Organize your gitlab copy of FastForth
 411 -------
 412
 413 download zip of last version
 414
 415 copy it to a subfolder, i.e. FastForth, created in your user folder
 416
 417 right clic on it to share it with yourself.
 418
 419 remember its shared name i.e. : //myPC/users/my/FastForth.
 420
 421 in file explorer then right clic on root to connect a network drive, copy shared name in drive name
 422 and choose a free drive letter a:, b: ...
 423
 424 Thus all relative paths will be linked to this drive, except the three \MSP430-FORTH\files.bat links.
 425 For all of them right clic select, select properties then check drive letter in target.
 426
 427 WARNING! if you erase a file directly in this drive or in one of its subfolders, no trash, the file is lost!
 428
 429
 430
 431 Minimal Software
 432 --
 433
 434 If you are under WINDOWS :
 435
 436     First, you download the TI's programmer from TI : http://www.ti.com/tool/MSP430-FLASHER.
 437     And the MSP430Drivers :
 438     http://software-dl.ti.com/msp430/msp430_public_sw/mcu/msp430/MSP430_FET_Drivers/latest/index_FDS.html
 439
 440     The next tool is TERATERM.EXE : http://logmett.com/index.php?/products/teraterm.html.
 441
 442     As scite is my editor, this github repository is fully configured for scite users.
 443     download the single file executable called sc1 (not the full download! ) :
 444     http://www.scintilla.org/SciTEDownload.html, then save it as \prog\wscite\scite.exe.
 445
 446     download GEMA preprocessor : https://sourceforge.net/projects/gema/files/gema/gema-1.4-RC/
 447
 448     The MacroAssembler AS :     http://john.ccac.rwth-aachen.de:8000/as/
 449
 450     and Srecord : http://srecord.sourceforge.net/download.html to convert HEX file to TI TXT files.
 451
 452     copy last 3 items onto their respective \prog subfolder.
 453
 454     ask windows to open .asm, .inc, lst, .mac, .4th, .f, .pat files with scite.exe
 455
 456
 457 If you are linux or OS X men, see FastForth.pdf.
 458
 459
 460 Build the program file
 461 ----------------------
 462
 463
 464 \forthMSP430FR.asm is the main file to compile FastForth. It calls :
 465
 466 open forthMSP430FR.asm with scite editor
 467
 468 uncomment the target as you want, i.e. MSP_EXP430FR5969
 469
 470 choose frequency, baudrate, UART handshake.
 471
 472 uncomment options switches as your convenience.
 473
 474 save file.
 475
 476 assemble (CTRL+0). A window asks you for 4 parameters:
 477
 478 set target as first param, i.e. MSP_EXP430FR5969,
 479
 480 then execute. the output will be MSP_EXP430FR5969.txt
 481
 482
 483
 484 Load Txt file (TI format) to target
 485 -----------------------------------
 486
 487     drag your target.txt file and drop it on prog.bat
 488
 489     or use scite internal command TOOLS: FET prog (CTRL+1).
 490
 491 nota : programming the device use SBW2 interface, so UART0 is free for serial terminal use.
 492
 493 If you want to program your own MSP430FRxxxx board, wire its pins TST, RST, 3V3 and GND
 494 to same pins of the launchpad, on eZ-FET side of the programming connector.
 495
 496
 497
 498 Connect the FAST FORTH target to a serial terminal
 499 -------------------------------------------------
 500
 501 you will need an USBtoUART cable with a PL2303TA or PL2303HXD device that allows both XON/XOFF
 502 and hardware control flow :
 503
 504     http://www.google.com/search?q=PL2303TA
 505     http://www.google.com/search?q=PL2303HXD
 506
 507 or USBtoUART bridge, with a CP2102 device and 3.3V/5V that allows XON/XOFF control flow :
 508
 509         search google: cp2102 module 3.3V
 510         http://www.silabs.com/products/mcu/Pages/USBtoUARTBridgeVCPDrivers.aspx
 511
 512     you must program CP2102 device to access 1382400 and 1843200 bds rates :
 513         http://www.silabs.com/Support%20Documents/Software/install_USBXpress_SDK.exe
 514         http://www.silabs.com/Support%20Documents/TechnicalDocs/an169.pdf
 515
 516 or a USBtoUART bridge, with a FT232RL device and 3.3V/5V for only hardware control flow:
 517
 518     WARNING! buy a FT232RL module with a switch 5V/3V3 and select 3V3.
 519
 520         http://www.google.com/search?q=FT232RL+module+3.3V
 521         http://www.ftdichip.com
 522
 523 or compatible 921600bds wireless module: RN42 (bluesmirf), RN4878...
 524
 525 How to configure the connection ?
 526 -------------------------------
 527
 528 1-    XON/XOFF control flow: Launchpad UARTn  <--> USBtoUART bridge <--> TERATERM
 529
 530    launchpad <--> UART2USB
 531          TXn ---> RX
 532          RXn <--- TX
 533          GND <--> GND
 534                 WARNING! DON'T CONNECT 5V RED WIRE!
 535
 536       TeraTerm configuration : see DTCforthMSP430fr5xxx.asm
 537
 538 If you plan to supply your target vith a PL2303 cable, open its box to weld red wire onto 3.3V pad.
 539
 540 2-    hardware control flow: Launchpad UARTn <--> USBtoUART bridge <--> TERATERM
 541
 542    Launchpad <--> UART2USB
 543          TXn ---> RX
 544          RXn <--- TX
 545          RTS ---> CTS  4th wire
 546          GND <--> GND
 547                 WARNING! DON'T CONNECT 5V !
 548
 549       TeraTerm configuration : see DTCforthMSP430fr5xxx.asm
 550
 551
 552 3-    Bluetooth module: Launchpad UARTn <--> RN42 <--> TERATERM
 553
 554    launchpad <--> wireless module
 555          TXn ---> RX
 556          RXn <--- TX
 557          RTS ---> CTS  4th wire
 558          GND <--> GND
 559         (CTS <--- RTS) 5th wire if necessary
 560
 561                  3V3 <--> 3V3
 562
 563       TeraTerm configuration : see DTCforthMSP430fr5xxx.asm
 564
 565
 566 Send a source file.f or file.4th to the FAST FORH target
 567 ------------------
 568
 569 Three bat files are done in \MSP430-FORTH that enable you to do all you want.
 570 drag and drop your source file on to.
 571 you can also open any source file with scite editor, and do all you want via its Tools menu.
 572
 573 If you have any downloading error, first verify in "LAST.4th" that all lines are
 574 correctly ended with CR+LF.
 575
 576
 577 SD_Card Load, Read, Write and Delete
 578 =============================================
 579
 580 First, hardware
 581 ---------------
 582
 583 If you have MSP-EXP430FR5994, nothing to do.
 584
 585 For the choice of a SD card socket be carefull, pin CD (Card Detect) must be present!
 586 google search: "micro SD card 9 pin"
 587 Look for the good wiring in /Launchpad.asm file
 588
 589 Compile with SD_Card addon
 590 --------------
 591
 592 in forthMSP430FR.asm, uncomment lines SD_CARD_LOADER,  SD_CARD_READ_WRITE, SD_TOOLS
 593 then compile for your target
 594
 595
 596
 597
 598 the commands
 599 ------------
 600
 601 With the LOAD" pathame" command you load your source files from a SD_CARD memory in both execute
 602 and compile modes. Idem for READ", WRITE" and DEL" commands.
 603
 604 See "SD_TESTS.f", a FORTH program done for example
 605
 606 If you remove the SD memory card reader and then reset, all SD\_IO pins are available except SD_CD obviously.
 607
 608 HowTo LOAD a sourcefile
 609 --------------
 610
 611         LOAD" path\filename.4th".
 612
 613 The file is interpreted by FORTH in same manner than from the serial terminal.
 614
 615 When EOF is reached, the file is automatically closed.
 616
 617 A source file can _LOAD"_ an other source file, and so on in the limit of available handles (up to 8).
 618
 619 HowTo READ a file
 620 --------------
 621
 622         READ" path\filename.ext".
 623
 624 The first sector of this file is loaded in BUFFER.
 625 To read next sectors, use the command READ that loads the next sector in the buffer,
 626 and leaves on the stack a flag that is true when the EOF is reached.
 627 The file is automatically closed. See tstwords.4th for basic usage.
 628
 629 The variable BufferLen keep the count of bytes to be read (0 to 512).
 630
 631 If you want to anticipate the end, use the CLOSE command.
 632
 633 HowTo WRITE a file
 634 ---------------
 635
 636         WRITE" path\filename.ext".
 637
 638 If the file does not exist, create it, else open it and set the write pointer at the end of the file,
 639 ready to append chars.
 640
 641 See example of use in \MSP430-FORTH\SD_TEST.f.
 642
 643 To overwrite an existing file: DEL" file" then  WRITE" file".
 644
 645 Use CLOSE to close the file.
 646
 647 HowTo delete a file
 648 ---------------
 649
 650         DEL" path\filename.ext". If the file is not found, do nothing, no error.
 651
 652 HowTo change DIRectory
 653 ---------------
 654
 655         LOAD" \misc".               \misc becomes the current folder.
 656         LOAD" ..\"                      parent folder becomes the current folder.
 657         LOAD" \"                                Root becomes the current folder.
 658
 659 Drive letters are always ignored.
 660
 661 Downloading source file to SD_Card
 662 ------------------------------------------
 663
 664 to download a source file (.f or.4th) onto SD_CARD target, use CopySourceFileToTarget\_SD\_Card.bat.
 665 or use scite.
 666 Double click on one of this bat files to see how to do.
 667
 668 If you have any downloading error, first verify in "LAST.4th" that all lines are
 669 correctly ended with CR+LF.
 670
 671 I2C DRIVERS
 672 ===========
 673
 674 The I2C\_Soft\_Master driver with normal/fast mode allows you to add then use any couple of pins to drive a bus I2C :
 675
 676  - without use of eUSCI UCBx
 677  - I2C\_Soft\_MultiMaster driver : same plus detection collision
 678  - plus I2C\_Slave driver that uses the eUSCI UCBx hardware
 679
 680
 681 Other interesting specificities :
 682 =====
 683
 684 Management of vocabularies (not ANSI):
 685 VOCABULARY, DEFINITIONS, ONLY, ALSO, PREVIOUS, CONTEXT, CURRENT, FORTH, ASSEMBLER.
 686 In fact, it's the the assembler that requires the vocabularies management.
 687
 688 Recognizing prefixed numbers %101011 (bin), $00FE (hex) and #220 (decimal).
 689
 690 ECHO / NOECHO
 691
 692 The words DEFER and IS are implemented. CR, EMIT, KEY, ACCEPT, QUIT and WARM are deferred words.
 693
 694 Error messages are colored (reverse video on ANSI terminal).
 695
 696 Assembly jumps are as FORTH one's : IF, ELSE, THEN, BEGIN, AGAIN, UNTIL, WHILE.
 697 Not canonical jumps are also available with JMP|?JMP to a defined word and GOTO|?GOTO to
 698 backward labels BW1 BW2 BW3 or forward labels FW1 FW2 FW3.
 699 These labels are for one use.
 700 Switch  within definitions between FORTH and Assembly contexts with words HI2LO and LO2HI.
 701 See examples in the TstWords.f file. This is perhaps the most interesting feature for development...
 702
 703
 704 The system is not responding ?
 705 ======
 706
 707 First, swich off then switch on. FORTH restarts as it was after the last PWR\_HERE command.
 708
 709 If the system is not restarted, press <reset> button on the MSP-EXP430FR5xxx ; FORTH restarts
 710 as it was after the last RST_HERE command.
 711
 712 If the system does not restart again, wire the TERMINAL TX pin to GND via 4k7 resistor then <reset> ;
 713 FORTH restarts as it is in the HEX file.
 714 Equivalent word : COLD + WIPE.
 715
 716 Here is the FastForth init architecture :
 717
 718         case 0 : when you type WARM, FORTH interpreter is restarted, no program lost.
 719                          the WARM display is preceded by "#0".
 720
 721         case 1 : Power ON ==> performs reset and the program beyond PWR_HERE is lost.
 722                          the WARM display is preceded by the SYSRSTIV value "#2".
 723
 724         case 1.1 : when you type PWR_STATE ==> the program beyond PWR_HERE is lost.
 725
 726         case 1.2 : If an error message (reverse video) occurs, PWR_STATE is automatically executed
 727                and the program beyond PWR_HERE is lost. In this way, any compilation error is
 728                followed by the complete erasure of the uncompleted word, or by that of
 729                the downloading source file causing this error. So, it is recommended to finish
 730                a source file with at least PWR_HERE to protect it against any subsequent error.
 731
 732         case 2 : <reset>  ==> performs reset and the program beyond RST_HERE is lost.
 733                          the WARM display is preceded by the SYSRSTIV value "#4".
 734
 735         case 2.1 : when you type COLD (software reset) ==> same effects.
 736                            the WARM display is preceded by the SYSRSTIV value "#6".
 737
 738         case 2.2 : when you type RST_STATE ==> the program beyond RST_HERE is lost.
 739
 740
 741         case 3 : when you type WIPE ==> all programs donwloaded from the terminal or the SD_Card are lost.
 742
 743
 744         case 4 : TERM_TX wired to GND via 4k7 during <reset> = DEEP_RST ===> performs reset, and all programs
 745              donwloaded from the terminal or the SD_Card are lost. The WARM display is preceded by "-4".
 746
 747         case 4.1 : software reset on failure (SYSRSTIV = 0Ah | SYSRSTIV >= 16h) ===> same effects
 748                            The WARM display is preceded by the SYSRSTIV value.
 749
 750         case 4.2 : writing -1 in SAVE_SYSRSTIV before COLD = software DEEP_RST ===> same effects
 751                            The WARM display is preceded by "-1".
 752
 753         case 5 : after FAST FORTH core compilation, the WARM displays SAVE_SYSRSTIV = 5. User may use this
 754              information before WARM occurs.
 755
 756
 757 If SD\_CARD extention and SD\_CARD memory with \BOOT.4TH included, the cases 1 to 4 starts it
 758 after displaying of WARM message.
 759
 760
 761 VOCABULARY ADD-ON
 762 ====
 763
 764 These words are not ANS94 compliant, they are those of F83 standard.
 765
 766 For example, after loading SD_TOOLS add-on, you can type: ALSO ASSEMBLER WORDS PREVIOUS WORDS
 767
 768     With ALSO ASSEMBLER, the vocabulary ASSEMBLER is added to the search CONTEXT thus the ASSEMBLER words
 769     become visible
 770
 771     WORDS display the words of ASSEMBLER then those of FORTH,
 772
 773     PREVIOUS remove the vocabulary ASSEMBLER form the CONTEXT, and the ASSEMBLER words become hidden,
 774
 775     so the last WORDS display only FORTH words.
 776
 777 In the forthMSP430FR_ASM.asm, see the FORTH word CODE that add ASSEMBLER to the search CONTEXT and the ASSEMBLER word ENDCODE
 778  that remove ASSEMBLER from search CONTEXT. Thus, the assembler words can be used only between CODE and ENDCODE.
 779
 780 The CONTEXT can grow up to 6 vocabularies by using the word ALSO.
 781
 782 If you want add words to the assembler you must type: ALSO ASSEMBLER DEFINITIONS,
 783 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.
 784
 785 Finally, FORTH ONLY DEFINITIONS limits the search CONTEXT to FORTH and the CURRENT vocabulary is FORTH.
 786
 787
 788 EMBEDDED ASSEMBLER
 789 ======
 790
 791 With the preprocessor GEMA the embedded assembler allows access to all system variables.
 792 See files \\config\\gema\\Target.pat.
 793 You can also access to VARIABLE, CONSTANT or DOES type words.
 794 see \MSP430-FORTH\TESTASM.4th.
 795
 796
 797
 798 HOW TO MIX assembly and FORTH ?
 799 ---
 800
 801 FAST FORTH knows two kinds of words :
 802
 803     low level assembly words starting with CODE <name> and ended with ENDCODE.
 804
 805     high level FORTH words beginning with : <name> and ended with ;
 806
 807
 808 Examples
 809
 810     CODE ADD    \ Assembly word "ADD", alias of word +
 811         ADD @PSP+,TOS
 812         MOV @IP+,PC
 813     ENDCODE
 814
 815
 816     : NOOP      \ FORTH word "NOOP", do nothing
 817         DUP
 818         DROP
 819     ;
 820
 821
 822
 823 To end a low level assembly word, the instruction MOV @IP+,PC jumps to the next FORTH word.
 824 This faster (4 cycles) and shorter (one word) instruction replaces the famous pair of assembly
 825 instructions : CALL #LABEL ... RET (4+4 cycles, 2+1 words). The register IP is the Interpretative Pointer.
 826
 827 High level FORTH word starts with a boot code DOCOL that save the IP pointer, load it with the first address
 828 of a list of execution addresses, then performs a postincrement branch to this first address.
 829 The list ends with the address of another piece of code EXIT (6 cycles) that restores IP before the instruction MOV @IP+,PC.
 830
 831
 832 here, the compilation of low level word ADD :
 833
 834                     header          \ compiled by the word CODE
 835     execution addr  ADD @PSP+,TOS
 836                     MOV @IP+,PC     \ instruction called NEXT
 837
 838 and the one of the high level word NOOP :
 839
 840                     header          \ compiled by the word :
 841     execution addr  CALL rDOCOL     \ boot code compiled by the word :
 842                     addr of DUP     \ execution addr of DUP
 843                     addr of DROP    \ execution addr of DROP
 844                     addr of EXIT    \ execution addr of EXIT compiled by the word ;
 845
 846
 847 _A high level FORTH word is a list of execution addresses preceded by a boot code and ending with EXIT address._
 848
 849
 850 WRITING RULES
 851 --
 852
 853 any low level FORTH words must be ended with the instruction MOV @IP+,PC (NEXT).
 854
 855         CODE TEST               \ CODE starts a low level word
 856             asm1                \ assembly instruction 1
 857             asm2                \ assembly instruction 2
 858             MOV @IP+,PC         \ NEXT
 859         ENDCODE                 \ end of low level word
 860
 861
 862 If you want to use the IP register, save it before and restore it before NEXT
 863
 864         CODE TEST1              \ CODE starts a low level word
 865             asm1                \ assembly instructions
 866             ...
 867             PUSH IP             \ save IP before use
 868             MOV #1,IP           \ assembly instruction that uses IP
 869             ...                 \ assembly instructions
 870             MOV @RSP+,IP        \ restore IP
 871             MOV @IP+,PC         \ NEXT
 872         ENDCODE                 \ end of low level word
 873
 874
 875 A little more complex, the case of mixing FORTH and assembly that is enabled by the words HI2LO, LO2HI and COLON
 876
 877         : MIX_FORTH_ASM         \ definition of a FORTH word starts with :
 878             SWAP
 879             DUP
 880         HI2LO                   \ FORTH to assembler switch
 881             asm1                \ assembly instruction
 882             asm2                \ assembly instruction
 883             ...                 \ you can freely use IP !
 884             ...                 \ assembly instructions
 885             MOV @RSP+,IP        \ restore IP
 886             MOV @IP+,PC         \ NEXT
 887         ENDCODE                 \ end of low level word
 888
 889 If we see the code "MIX\_FORTH\_ASM" after compilation :
 890
 891             header              \ compiled by :
 892     exec@   CALL rDOCOL         \ boot code compiled by the word :
 893             addr                \ execution addr of SWAP
 894             addr                \ execution addr of DUP
 895             next addr           \ addr of asm1, compiled by HI2LO
 896             asm1                \ assembly instruction
 897             asm2                \ assembly instruction
 898             ...                 \ you can freely use IP !
 899             ...                 \ assembly instructions
 900             MOV @RSP+,IP        \ restore IP saved by :
 901             MOV @IP+,PC         \ NEXT
 902
 903 the instruction "CALL rEXIT" (CALL R7), have EXIT address as rEXIT content.
 904
 905
 906 going a step further :
 907
 908         CODE MIX_ASM_FORTH      \ CODE starts a low level word
 909             asm1                \ assembly instruction 1
 910             asm2                \ assembly instruction 2
 911         COLON                   \ starts high level
 912             word1
 913             word2
 914         ;                       \ end of high level word
 915
 916
 917 If we see this code "MIX\_ASM\_FORTH" after compilation :
 918
 919             header              \ compiled by CODE
 920     exec@   asm1                \ assembly instruction 1
 921             asm2                \ assembly instruction 2
 922             CALL rDOCOL         \ compiled by COLON
 923             addr1               \ of word1
 924             addr2               \ of word2
 925             addr of EXIT        \ the word ; compiles address of EXIT that restores IP then executes MOV @IP+,PC
 926
 927
 928 A new step
 929
 930         : MIX_FORTH_ASM_FORTH   \ definition of a FORTH word starts with :
 931             word1
 932             word2
 933             ...
 934         HI2LO                   \ FORTH to assembler switch
 935             MOV #0,IP           \ IP is free for use
 936             asm1
 937             ...
 938         LO2HI                   \ assembler to FORTH switch
 939             word3
 940             word4
 941         ;                       \ end of high level word
 942
 943 the compiled result
 944
 945             header              \ compiled by :
 946     exec@   CALL rDOCOL         \ boot code compiled by the word :
 947             addr1               \ of word1
 948             addr2               \ of word2
 949             ...
 950             next addr           \ compiled by HI2LO
 951             MOV #0,IP           \ IP is free for use
 952             asm1                \ assembly instruction
 953             ...
 954             CALL #EXIT          \ compiled by LO2HI (10 cycles switch)
 955             addr3               \ of word3
 956             addr4               \ of word4
 957             addr5               \ of EXIT
 958
 959 EXIT is used twice !
 960
 961 the first time, by LO2HI :
 962
 963     EXIT    MOV @RSP+,IP    \ 2 pop into IP the PC pushed on return stack by CALL #EXIT
 964             MOV @IP+,PC     \ 4 execute the routine at addr3
 965
 966 then at the end of FORTH word (addr5):
 967
 968     EXIT    MOV @RSP+,IP    \ 2 pop old IP from return stack
 969             MOV @IP+,PC     \ 4 execute the routine pointed by the old IP
 970
 971
 972 Still another step :
 973
 974         CODE MIX_ASM_FORTH_ASM  \ CODE starts a low level word
 975             asm1                \ assembly instruction
 976             asm2                \ assembly instruction
 977         COLON                   \ starts high level
 978             word
 979             ...
 980         HI2LO                   \ FORTH to assembler switch
 981             asm3                \ assembly instruction
 982             asm4                \ assembly instruction
 983             MOV @RSP+,IP        \ restore IP
 984             MOV @IP+,PC         \ NEXT
 985         ENDCODE                 \ end of low level word
 986
 987 In fact, an exclusive of FAST FORTH, the start of a word FORTH can be placed anywhere :
 988
 989         CODE MIX_ASM_FORTH_ASM_FORTH
 990             asm
 991             asm
 992             ...
 993         COLON                   \ starts high level
 994             word
 995             word
 996             ...
 997         HI2LO                   \ FORTH to assembler switch
 998             asm
 999             asm
1000            ...
1001         LO2HI                   \ assembler to FORTH switch
1002             word
1003             word
1004             ...
1005         ;                       \ end of high level word
1006
1007 with the compiled result :
1008
1009             header              \ compiled by CODE
1010     exec@   asm
1011             asm
1012             CALL rDOCOL         \ compiled by COLON
1013             addr
1014             addr
1015             next address        \ compiled by HI2LO
1016             asm
1017             asm
1018             CALL #EXIT          \ compiled by LO2HI
1019             addr
1020             addr
1021             EXIT addr           \ that restores IP from return stack and then executes MOV @IP+,PC
1022
1023 As we see, IP is saved only once, it's logical.
1024
1025
1026 ASSEMBLER WITHOUT LABELS ? YES !
1027 ---
1028
1029 To compare AS macro assembler and FastForth embedded assembler,
1030 compare files /ADDON/fixpoint.asm and /MSP430-FORTH/FIXPOINT.f
1031
1032 The syntax of FastForth assembler borrows FORTH's one :
1033
1034     CODE TEST_IF_THEN
1035         CMP #1,R8           \ set Z,N,V, flags
1036         0= IF               \ irritating, the "IF 0=" upside down, isn't it?
1037             ADD R8,R9       \ true part of comparaison
1038         THEN
1039         ...                 \ the next
1040         ...
1041         MOV @IP+,PC         \ don't forget...
1042     ENDCODE                 \ don't forget...
1043
1044 and the complete version :
1045
1046     CODE TEST_IF_ELSE_THEN
1047         CMP #1,R8           \ set Z,N,V, flags
1048         0= IF               \
1049             ADD R8,R9       \ true part of comparaison
1050         ELSE
1051             SUB R8,R9       \ false part of comparaison
1052         THEN
1053         ...                 \ following for the two branches
1054         MOV @IP+,PC         \ don't forget...
1055     ENDCODE                 \ don't forget...
1056
1057 test for loop back version BEGIN ... UNTIL
1058
1059     CODE TEST_BEGIN_UNTIL
1060         MOV #8,R10
1061         BEGIN
1062             SUB #1,R10      \ set Z,N,V flags
1063         0= UNTIL            \ loop back to BEGIN if flag Z is not set
1064         ...
1065         MOV @IP+,PC
1066     ENDCODE
1067
1068 test for out of loop version BEGIN ... WHILE ... REPEAT
1069
1070     CODE TEST_BEGIN_WHILE_REPEAT
1071         MOV #8,R10
1072         BEGIN
1073             SUB #1,R10      \ set Z,N,V flags
1074         0<> WHILE           \ go to out of loop if X=0 (Z flag =1)
1075             XOR #1,R9
1076         REPEAT              \ unconditionnal loop back to BEGIN
1077         ...                 \ out of loop here
1078         MOV @IP+,PC
1079     ENDCODE
1080
1081 infinite loop :
1082
1083     CODE TEST_BEGIN_AGAIN
1084         BEGIN
1085             ADD #1,R9
1086         AGAIN               \ unconditionnal loop back to BEGIN
1087     ENDCODE
1088
1089 to quit this infinite loop, press reset.
1090
1091
1092 We can nest several conditional branches :
1093
1094     CODE TEST_NESTED_IF_ELSE
1095         CMP #0,R10
1096         0= IF
1097             CMP #0,R10
1098             0= IF
1099                 MOV #0,R11
1100             ELSE
1101                 SUB #1,R11
1102             THEN
1103         ELSE
1104             MOV #1,R11
1105         THEN
1106         MOV @IP+,PC
1107     ENDCODE
1108
1109 another nest :
1110
1111     CODE TEST_NESTED_BEGIN_AGAIN_IF
1112         MOV #8,R9
1113         BEGIN
1114             CMP #-1,R9
1115             0= IF
1116                 MOV @IP+,PC \ out of test_NESTED_BEGIN_AGAIN_IF
1117             THEN
1118             SUB #1,R9
1119         AGAIN
1120     ENDCODE
1121
1122
1123 you can also MIX conditional branches with a mix of FORTH/assembly :
1124
1125     see TEST5 in the demo file \MSP430-FORTH\TESTASM.4TH
1126
1127
1128 ...but not quite !
1129 ---
1130
1131 unconditionnal backward jump :
1132
1133         CODE UNCOND_BACKWARD
1134             asm
1135             asm
1136             JMP TEST_NESTED_BEGIN_AGAIN_IF  \ jump backward to a predefined word
1137         ENDCODE
1138
1139 conditionnal backward jump :
1140
1141         CODE COND_BACKWARD
1142             asm
1143             CMP #0,R8
1144             S< ?JMP TEST_NESTED_BEGIN_AGAIN_IF    \ jump backward if negative
1145             asm
1146             MOV @IP+,PC
1147         ENDCODE
1148
1149
1150 But FAST FORTH have one pass assembler, not able to make forward jump.
1151
1152 I have added possibility of several "non canonical" jumps, up to 3 backward and up to 3 forward imbricated jumps to label :
1153
1154     \ C UM/MOD   udlo|udhi u1 -- ur uq
1155     CODE UM/MOD
1156         MOV @PSP+,W     \ 2 W = DIVIDENDhi
1157         MOV @PSP,S      \ 2 S = DIVIDENDlo
1158     \ T.I. ROUTINE  Section 5.1.5 of MSP430 Family Application Reports
1159         MOV #0,Y        \ 1 CLEAR RESULT
1160         MOV #16,X       \ 2 INITIALIZE LOOP COUNTER
1161     BW1 CMP TOS,W       \ 1
1162         U< ?GOTO FW1    \ 2 if not carry
1163         SUB TOS,W       \ 1 if carry DIVIDENDhi-divisor
1164     FW1                 \   FW1 label is resolved therefore reusable
1165     BW2 ADDC Y,Y        \ 1 RLC quotient
1166         U>= ?GOTO FW1   \ 2 if carry Error: result > 16 bits
1167         SUB #1,X        \ 1 Decrement loop counter
1168         <0 ?GOTO FW2    \ 2 if 0< terminate w/o error
1169         ADD S,S         \ 1 RLA DIVIDENDlo
1170         ADDC W,W        \ 1 RLC DIVIDENDhi
1171         U< ?GOTO BW1    \ 2 if not carry    14~ loop
1172         SUB TOS,W       \ 1 if carry DIVIDENDhi-divisor
1173         BIS #1,SR       \ 1 SETC
1174         GOTO BW2        \ 2                 14~ loop
1175     FW2 BIC #1,SR       \ 1 CLRC  No error, C = 0
1176     FW1                 \  Error indication in C
1177     \ END T.I. ROUTINE  Section 5.1.5 of MSP430 Family Application Reports
1178         MOV W,0(PSP)    \ 3 remainder on stack
1179         MOV Y,TOS       \ 1 quotient in TOS
1180         MOV @IP+,PC     \ 4
1181     ENDCODE
1182
1183
1184 SYMBOLIC ASSEMBLER ? YES !
1185 --
1186
1187 I have discovered a little semantic preprocessor "GEMA", just like that FAST FORTH have its symbolic assembler !
1188
1189     \config\gema\DEVICE.pat contains memory map and vectors for a specified DEVICE
1190     \config\gema\LAUNCHPAD.pat is the I/O config file for specific LAUNCHPAD (or application)
1191
1192 gema translates also FORTH registers in ASM registers (R0 to R15)
1193
1194 If you have created a network drive from your local gitlab directory, it's easy :
1195 with scite editor open a file.f, then select in the menu "tools" the items "preprocess..."
1196
1197 furnished examples : see \MSP430-FORTH\
1198 Enjoy !
1199
1200
1201 COMPILE FAST FORTH FOR YOUR MODULE
1202 --
1203
1204 1- in forthMSP430FR.asm "TARGET configuration SWITCHES"  create a line for your target, example:
1205
1206     ;MY_MSP430FR5738_1 ; compile for my own MSP430FR5738 miniboard V1
1207
1208 2- create your MSP430FR5738_1.asm and MSP430FR5738.inc from another target.asm and device.inc as pattern,
1209 then customize declarations.
1210
1211 3- in ThingsInFirst.inc add one "device.inc" item:
1212
1213         .IFDEF MY_MSP430FR5738_1
1214     UCA0_UART   ; for device.inc file below, defines uart used by FORTH input terminal
1215     LF_XTAL     ; for device.inc file below, defines if your module have a 32768 Hz xtal, to enable it.
1216     UCB0_SD     ; for device.inc file below, defines UC used for SD Card driver if used
1217         .include "MSP430FR5738.inc"  ; include device declarations
1218         .ENDIF
1219
1220 4- in TargetInit.asm add one "target.asm" item:
1221         .IFDEF MY_MSP430FR5738_1
1222             .include MY_MSP430FR5738.asm
1223         .ENDIF
1224
1225
1226 Then, for your source files:
1227
1228 1- create a \config\gema\device.pat file if not exist, from device.inc and another device.pat as pattern.
1229
1230 2- create your \config\gema\target.pat file from target.asm and another target.pat as pattern.
1231
1232 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
1233 that is the reset state of FastForth...
1234
1235 START YOUR PROJECT
1236 --
1237
1238 How to start your project ?
1239
1240 I show you, assuming you are working from the scite editor with its enhanced tools menu.
1241
1242 First you create two files : project.f and test.f
1243
1244 PROJECT.f :
1245
1246     ; ----------------------------------------------------
1247     ; MSP430FR5969 MSP_EXP430FR5969 8MHZ 921600bds PROJECT.f
1248     ; ----------------------------------------------------
1249
1250     [DEFINED] {PROJECT} [IF] {PROJECT} [THEN] \ remove {PROJECT} if exist (memory managment)
1251
1252     MARKER {PROJECT}
1253
1254
1255 here you append your already tested routines :
1256
1257     CODE FIRST  \ assembler CODE words are FORTH executable
1258         ...
1259     MOV @IP+,PC \ NEXT
1260     ENCODE
1261
1262     ASM TWO     \ assembler ASM words are not FORTH executable and can only be used in assembler mode
1263         ...     \ used to define interrupt routines, or subroutines called by CALL...
1264     RET         \ and ended by RET or RETI.
1265     ENDASM
1266
1267     CODE THREE
1268         ...
1269     CALL #TWO   \ CALL only ASM words
1270         ...
1271     MOV @IP+,PC \ NEXT
1272     ENCODE
1273
1274     ASM WDT_INT             \ interrupt routine
1275         ...
1276         ...
1277     BIC #WDTIFG,&SFRIFG1    \ reset WDT_INT flag
1278     BIC #$F8,0(RSP)         \ set CPU ON and GIE OFF in saved SR
1279     RETI                    \
1280     ENDASM
1281
1282     ;
1283
1284 then finish with this 2 "magic" words plus one optional : START, STOP and optional BACKGROUND
1285
1286     ASM BACKGROUND          \ (optional)
1287     BW1
1288         ...                 \ insert here your background task
1289         ...
1290         ...
1291     BIS &LPM_MODE,SR        \
1292     GOTO BW1
1293     ENDASM                  \
1294
1295
1296
1297
1298
1299     CODE START              \ to init your app
1300         ...                 \ init assembly part
1301     MOV #WDT_INT,&VEC_WDT   \ init WDT vector interrupt
1302         ...
1303     BIC #RC5,&P1REN         \ init I/O
1304         ...
1305
1306     MOV #SLEEP,X            \ redirect default background task to yours (optional)
1307     MOV #BACKGROUND,2(X)    \
1308
1309     COLON
1310         ...                 \ init FORTH part
1311
1312         LIT RECURSE IS WARM \ replace WARM by START
1313         ['] WARM >BODY      \ and end START with default WARM
1314         EXECUTE             \ that unlock I/O, start FORTH process
1315     ;                       \ then fall down to sleep state, waiting any interrupt...
1316
1317
1318     CODE STOP               \ to properly stop your app
1319         MOV #SLEEP,X        \ restore the default background (optional)
1320         ADD #4,X            \ (word SLEEP can only be seen in assembler mode, not in FORTH)
1321         MOV X,-2(X)
1322     COLON
1323         ['] WARM >BODY
1324         IS WARM             \ remove START from FORTH init process
1325         ECHO                \ to always retrieve FORTH input terminal
1326         COLD                \ reset CPU, interrupt vectors and restart FORTH.
1327     ;
1328
1329
1330     RST_HERE
1331
1332     START       ; let's go!
1333
1334 end of file
1335
1336
1337 Each time you download this project file, the word {PROJECT} removes all subsequent definitions,
1338 and the word RST_HERE protects the PROJECT against RESET.
1339
1340 The word START allows you to include your app init into FORTH's one.
1341 The word STOP unlink your app from FORTH init process.
1342
1343 Look at the file RC5toLCD.f to retrieve this structure.
1344
1345
1346
1347 TEST.f :
1348
1349     \ ----------------------------------
1350     \ MSP-EXP430FR5969_8MHZ_TEST.f
1351     \ ----------------------------------
1352
1353     RST_STATE   \ memory managment
1354
1355     here you write your routine to test
1356
1357     CODE TEST
1358     ...
1359     ...
1360     MOV @IP+,PC
1361     ENDCODE
1362
1363
1364     PWR_HERE    \ test.f content is protected against POWER OFF, but volatile with <reset>
1365
1366
1367 Each time you download this TEST file, the word RST\_STATE clears memory content beyond PROJECT.
1368
1369 let's go
1370 --
1371
1372 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.
1373
1374 If the test don't work, modify it in the test.f file, then reload it.
1375
1376 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 !
1377
1378 Good luck !
1379
1380
1381 ANNEXE
1382 --
1383
1384 The embedded assembler don't recognize the (useless) TI's symbolic addressing mode: ADD.B EDE,TONI.
1385
1386 REGISTERS correspondence (the preprocessor gema.exe allow you to use FASTFORTH or TI registers's names).
1387
1388     embedded ASM    TI      FASTFORTH   comment
1389
1390         R0          PC      PC          Program Counter
1391         R1          SP      RSP         Return Stack Pointer
1392         R2          SR/CG1              Status Register/Constant Generator 1
1393         R3          CG2                 Constant Generator 2
1394         R4          R4      R (rDODOES) contents address of xdodoes
1395         R5          R5      Q (rDOCON)  contents address of xdocon
1396         R6          R6      P (rDOVAR)  contents address of RFROM
1397         R7          R7      M (rDOCOL)  contents address of xDOCOL (DTC=1)
1398         R8          R8      Y           scratch register
1399         R9          R9      X           scratch register
1400         R10         R10     W           scratch register
1401         R11         R11     T           scratch register
1402         R12         R12     S           scratch register
1403         R13         R13     IP          Interpretation Pointer
1404         R14         R14     TOS         Top Of parameters Stack
1405         R15         R15     PSP         Parameters Stack Pointer
1406
1407 REGISTERS use
1408
1409     The FASTFORTH registers rDOCOL, rDOVAR, rDOCON and rDODOES must be preserved.
1410     If you use them, PUSHM #4,M before and POPM #4,M after.
1411     and if you use them you must not at the same time call (or jump to) any FORTH words!
1412
1413     don't use R3 and use R2 only with BIC, BIT, BIS instructions in register mode.
1414
1415
1416 PARAMETERS STACK use
1417
1418     The register TOS (Top Of Stack) is the first cell of the Parameters stack.
1419     The register PSP (Parameters Stack Pointer) points the second cell.
1420
1421     to push one cell on the PSP stack :
1422
1423         SUB #2,PSP                  \ insert a empty 2th cell
1424         MOV TOS,0(PSP)              \ fill this 2th cell with first cell
1425         MOV <what you want>,TOS     \ MOV or MOV.B <what you want>,TOS ; i.e. update first cell
1426
1427     to pop one cell from the PSP stack :
1428
1429         MOV @PSP+,TOS               \ first cell TOS is lost and replaced by the 2th.
1430
1431     don't never pop a byte with instruction MOV.B @PSP+, because generates a stack misalignement...
1432
1433 RETURN STACK use
1434
1435     register RSP is the Return Stack Pointer (SP).
1436
1437     to push one cell on the RSP stack :
1438
1439         PUSH <what you want>        \
1440
1441     to pop one cell from the RSP stack :
1442
1443         MOV @RSP+,<where you want>   \
1444
1445     don't never pop a byte with instruction MOV.B @RSP+, ...
1446
1447
1448     to push multiple registers on the RSP stack :
1449
1450         PUSHM #n,Rx                 \  with 0 <= x-(n-1) < 16
1451
1452     to pop multiple registers from the RSP stack :
1453
1454         POPM #n,Rx                  \  with 0 <= x-(n-1) < 16
1455
1456     PUSHM order : PSP,TOS, IP,  S,  T,  W,  X,  Y, rEXIT,rDOVAR,rDOCON, rDODOES, R3, SR,RSP, PC
1457     PUSHM order : R15,R14,R13,R12,R11,R10, R9, R8,  R7  ,  R6  ,  R5  ,   R4   , R3, R2, R1, R0
1458
1459     example : PUSHM #6,IP pushes IP,S,T,W,X,Y registers to return stack
1460
1461     POPM  order :  PC,RSP, SR, R3, rDODOES,rDOCON,rDOVAR, rEXIT,  Y,  X,  W,  T,  S, IP,TOS,PSP
1462     POPM  order :  R0, R1, R2, R3,   R4   ,  R5  ,  R6  ,   R7 , R8, R9,R10,R11,R12,R13,R14,R15
1463
1464     example : POPM #6,IP   pulls Y,X,W,T,S,IP registers from return stack
1465
1466     error occurs if n is out of bounds
1467
1468
1469 CPUx instructions RRCM,RRAM,RLAM,RRUM
1470
1471     example : RRUM #3,Y      \ Y (R8) register is Unsigned Right shifted by n=3
1472
1473     error occurs if 1 > n > 4
1474
1475
1476 conditionnal jumps use with symbolic assembler
1477
1478     0=    with IF UNTIL WHILE ?JMP ?GOTO
1479     0<>   with IF UNTIL WHILE ?JMP ?GOTO
1480     U>=   with IF UNTIL WHILE ?JMP ?GOTO
1481     U<    with IF UNTIL WHILE ?JMP ?GOTO
1482     S<    with IF UNTIL WHILE ?JMP ?GOTO
1483     S>=   with IF UNTIL WHILE ?JMP ?GOTO
1484     0>=   with IF UNTIL WHILE
1485     0<    with ?JMP ?GOTO
1486