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