README.md

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