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 < 6 kbytes.
   6 If your purpose is programming a MSP430FRxxxx in assembler, FAST FORTH is the Swiss army knife you absolutely need!
   7
   8 With a load, read,create, write, delete SD_CARD files driver, + source files direct copy from PC to SD_Card, its size is still < 9Kb.
   9 It works with all SD CARD memories from 64MB to 64GB. Count 14/11 clock cycles to read/write a byte, with SPI_CLK = MCLK...
  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         Tested on MSP-EXP430{FR5969,FR5994,FR6989,FR4133} launchpads and CHIPSTICKFR2433, at 0.5, 1, 2, 4, 8, 16 MHz,
  13     and 24MHz on a MSP430FR5738 module.
  14
  15         Files launchpad_3Mbd.txt are 16threads vocabularies 16MHz executables, with 3MBds XON/XOFF terminal,
  16     Launchpad_115200.txt files are same except 115200Bds for unlucky linux men without TERATERM.
  17     For the launchpad MSP-EXP430FR5994 with SD_CARD, full version is available. For others, you must recompile
  18     forthMSP430FR.asm with SD_CARD_LOADER and SD_CARD_READ_WRITE switches turned ON (uncomment their line).
  19
  20     Once the Fast Forth code is loaded in the target FRAM memory, you can add it assembly code or FORTH code, or both,
  21     by downloading your source files that embedded Fast Forth interprets and compiles. To do, you only need teraterm.exe
  22     as input terminal and an USBtoUART bridge to connect your target.
  23
  24     Beforehand, the preprocessor GEMA, by means of a target.pat file, will have translated your source file.f
  25     in a targeted source file.4th ready to download.
  26     A set of .bat files is furnished to do this automatically. See it all in the \MSP430-FORTH folder.
  27
  28         The download, interpretation and compilation of a source file.4th is done at a throughput of 40/80/120 kbytes/sec
  29     with a 8/16/24 MHz clock. Considering a ratio 5/1, that of the compiled code is 8/16/24 kbytes/sec.
  30
  31     After downloading of complementary words in COMPxMPY.f, FastForth executes CORETEST.4th without errors
  32     which ensures its compatibility with the FORTH CORE ANS94 standard.
  33     For MSP430FR4133 choose COMPSMPY.f, COMPHMPY.f for all others.
  34
  35     Notice that FAST FORTH interprets lines up to 80 chars, only SPACE as delimiter, only CR+LF as EOL, and BACKSPACE.
  36     And that memory access is limited to 64 kbytes. You can always create FORTH words to access data beyond this limit...
  37
  38     Finally, using the SCITE editor as IDE, you can do everything from its "tools" menu.
  39
  40 What is new ?
  41 -------------
  42
  43     FastForth V2.0, major version.
  44
  45     Word TIB is deprecated and replaced by CIB (Current Input Buffer).
  46     Word CR generates CR+LF instead of CR. TYPE is rewritten in assembly.
  47     Added half duplex input terminal for Bluetooth or wifi bridge use.
  48     To do, set HALFDUPLEX switch in forthMSP430FR.asm before compiling.
  49     If you set half duplex mode, add also echo local in teraterm terminal configuration.
  50     tested with bluesmirf RN42 module at 921600bds with 4 and 5 wires config.
  51
  52     Added fixed point s15q16 numbers. Thus FAST FORTH recognises :
  53     unsigned/signed numbers u/n (u <= 65535)/(-32768 <= n <= 32767),
  54     unsigned/signed double numbers ud/d by adding a decimal point (ud <= .4294967295)/(-.2147483648 <= d <= .2147483647),
  55     and s15q16 signed numbers by adding a comma (-32768,00000 <= s15q16 <= 32767,00000).
  56     The internal or external words set {FIXPOINT} adds the words: HOLDS F+ F- F/ F#S F* F. S>F, D>F and 2CONSTANT.
  57
  58     Fixed issue about the word LOAD": when called from a word, returns well into this calling word.
  59     Note that with MSP430FR57xx family, SDIB uses PAD, due to lack of RAM.
  60
  61     With the BOOTLOADER option, QUIT becomes a DEFERed word to easily enable/disable bootloader:
  62     ' BOOT IS QUIT     enables bootloader.
  63     ' (QUIT) IS QUIT   disables bootloader.
  64
  65     Same logic as QUIT, ACCEPT is a DEFERed word only with SD_CARD_LOADER option.
  66
  67     Added QUIETBOOT option to enable BOOT without displaying; use with care...
  68
  69     V162.
  70
  71     Added a set of words to enable conditional interpretation/compilation : MARKER [DEFINED] [UNDEFINED] [IF] [ELSE]
  72     [THEN]. A MARKER word (defined as {word} to well see it) allows you to wipe some program even if loaded in memory
  73     below RST_STATE boundary. See conditional compilation source files in \MSP430-FORTH.
  74
  75     All interpretation/compilation errors now execute POWER_STATE, so any incorrect definition
  76     and all its source file will be automatically erased.
  77
  78     Added a bootloader option which loads BOOT.4TH from SD_Card memory.
  79
  80
  81         V161.
  82
  83     SD_Card driver works also with software multiplier (with MSP430FR4133)
  84     added SLEEP and (SLEEP) words enabling user access to background task, see ACCEPT in forthMSP430FR.asm and see use
  85     in RC5toLCD.f
  86
  87     You can type double numbers by inserting a decimal point.
  88     Example :   $-12 is processed as 16 bits negative number.
  89                 $-.12 or $-1.2 or $-12. are processed as 32 bits negative numbers.
  90
  91     WARNING! XON/XOFF no longer works with new Prolific driver v3.8.12.0 (03/03/2017)...
  92              Waiting next update, get /prog previous PL2303_Prolific_DriverInstaller_v1160.exe (or .zip).
  93
  94         FAST FORTH V160, major version.
  95
  96     Accept SD_Card from 64 MB (FAT16) up to 64 GB (FAT32), excepted MSP-EXP430FR4133.
  97     Note that Windows 10 no longer offers the FAT32 format for the highest sizes of SD_CARD memory.
  98     So you must use an alternative to do, for example: https://www.partitionwizard.com.
  99
 100
 101     in SD_TOOLS the word SECT_D (dump sector) use a 32 bits number.
 102                 added the word CLUST_D (dump first sector of a cluster). Usage (notice the point): number. CLUST_D
 103
 104     PREVIOUS versions
 105
 106     Added direct file transfer from PC to the target SD_CARD.
 107     Measured throughput with "HCI" SD CARD: 90 kbytes/s at 3Mbauds and 16MHz target clock.
 108     You can do it from scite editor (menu Tools) or by using specific bat file.
 109     Double click on it to see how to do.
 110
 111     JTAG and BSL signatures (FF80h-FF88h) are protected against overwrite, typically during source file download.
 112
 113     added signed number prefixes $ (hex), % (bin) and # (decimal) to supersede current BASE.
 114
 115         Added words ASM and ENDASM to create assembler words that are not interpretable by FORTH
 116     i.e. that are called by {CALL|INTERRUPT} and ended by {RET|RETI}. These so created words can be used only in ASSEMBLER context.
 117
 118         In the embedded assembler, added 3 backward BW1 BW2 BW3 and 3 forward FW1 FW2 FW3 jump labels to use with GOTO, ?GOTO.
 119     These labels are for single use (one jump for one label) but immediately reusable once resolved.
 120
 121         you can compile up to 32 threads vocabularies.
 122
 123         Memory management :
 124         Fast Forth defines 4 levels of program memory with this words :
 125                 WIPE (and any system failure) that resets program memory, vectors interrupts and any DEFERred words,
 126                 RST_HERE / RST_STATE that sets / resets the boundary of program protected against <reset> and COLD,
 127                 PWR_HERE / PWR_STATE that sets / resets the boundary of program protected against power ON/OFF,
 128                 and nothing, i.e. volatile program.
 129
 130         You can download source files with hardware and/or software control flow (i.e. without line or char delays) up to:
 131                 134400  bds @ 500kHz
 132         268800  bds @ 1MHz
 133         614400  bds @ 2MHz
 134         1228800 bds @ 4MHz
 135         2457600 bds @ 8MHz
 136         3000000 bds @ 16MHZ
 137         6000000 bds @ 24MHz with MSP430FR57xx devices
 138     See main file DTCforthMSP430FR5xxx.asm for the list of reliable baudrates.
 139
 140         FAST FORTH can be adjusted by selection of SWITCHES in the source file to reduce its size according
 141         to your convenience. To do, comment/uncomment their line.
 142
 143     for your application, select the mode LPM{0,1,2,3,4} that enables wake on FAST FORTH input, depending of family:
 144     FR2xxx: LPM0, FR57xx : LPM0 to LPM2, FR59xx : LPM0 to LPM4.
 145
 146     DEEP_RST (RESET + WIPE) can be hardware performed via the programmation interface (Vcc,RX,TX,RST,TEST,GND).
 147
 148
 149 Many thanks to Brad Rodriguez
 150 -----------------------------
 151
 152 for his CamelForth which served me as a kind of canvas.
 153 And also to Matthias Koch for its ideas about s15.16 implementation.
 154
 155 Unlike CamelForth this FORTH is a "Direct Threaded Code", with an embedded assembler following the standard syntax,
 156 not the one used in the world Forth.
 157
 158 Its core is fully compliant with the standard ANS.
 159
 160 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.
 161
 162 What's this and why?
 163 ---
 164
 165 I have first programmed atmel tiny devices.
 166 Particularly I2C master driver to have both I2C slave and I2C master on a ATtiny461.
 167 which means a lot of back and forth between the editor, assembler, the programmer and the test in situ.
 168
 169 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.
 170
 171 The advent of chip MSP430 TEXAS INSTRUMENT with embedded FRAM gave me the idea to do it again : FAST FORTH was born.
 172
 173 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.
 174
 175 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.
 176
 177
 178 Content
 179 -------
 180
 181 With a size of about 6 kb, Fast Forth contains 119 words:
 182
 183     ASM            CODE           HI2LO          COLD           WARM           (WARM)         WIPE           RST_HERE
 184     PWR_HERE       RST_STATE      PWR_STATE      MOVE           LEAVE          +LOOP          LOOP           DO
 185     REPEAT         WHILE          AGAIN          UNTIL          BEGIN          THEN           ELSE           IF
 186     ;              :              DEFER          DOES>          CREATE         CONSTANT       VARIABLE       POSTPONE
 187     RECURSE        IMMEDIATE      IS             [']            ]              [              \              '
 188     ABORT"         ABORT          QUIT           EVALUATE       COUNT          LITERAL        ,              EXECUTE
 189     >NUMBER        FIND           WORD           ."             S"             TYPE           SPACES         SPACE
 190     CR             (CR)           NOECHO         ECHO           EMIT           (EMIT)         ACCEPT         KEY
 191     (KEY)          C,             ALLOT          HERE           .              D.             U.             SIGN
 192     HOLD           #>             #S             #              <#             BL             STATE          BASE
 193     >IN            CPL            CIB            PAD            J              I              UNLOOP         U<
 194     >              <              =              0>             0<             0=             DABS           ABS
 195     NEGATE         XOR            OR             AND            -              +              C!             C@
 196     !              @              DEPTH          R@             R>             >R             ROT            OVER
 197     SWAP           NIP            DROP           ?DUP           DUP            LIT            EXIT
 198
 199 ...size that includes its embedded assembler of 71 words:
 200
 201     ?GOTO          GOTO           FW3            FW2            FW1            BW3            BW2            BW1
 202     ?JMP           JMP            REPEAT         WHILE          AGAIN          UNTIL          ELSE           THEN
 203     IF             0=             0<>            U>=            U<             0<             0>=            S<
 204     S>=            RRUM           RLAM           RRAM           RRCM           POPM           PUSHM          CALL
 205     PUSH.B         PUSH           SXT            RRA.B          RRA            SWPB           RRC.B          RRC
 206     AND.B          AND            XOR.B          XOR            BIS.B          BIS            BIC.B          BIC
 207     BIT.B          BIT            DADD.B         DADD           CMP.B          CMP            SUB.B          SUB
 208     SUBC.B         SUBC           ADDC.B         ADDC           ADD.B          ADD            MOV.B          MOV
 209     RETI           LO2HI          COLON          ENDASM         ENDCODE        (SLEEP)        SLEEP
 210
 211 ...everything you need to program effectively in assembly or FORTH or mix, as you want. See examples in \MSP430-FORTH.
 212
 213
 214 Here are kernel compilation options:
 215
 216 CONDCOMP which enable conditional compilation:
 217
 218     [DEFINED]      [UNDEFINED]    [IF]           [ELSE]         [THEN]         COMPARE        MARKER
 219
 220 SD\_CARD\_LOADER to load FORTH source files from SD_CARD
 221
 222     LOAD"         (ACCEPT)
 223
 224 SD\_CARD\_READ\_WRITE to read write delete files and direct copy from TERMinal input to SD_card
 225
 226     TERM2SD"       SD_EMIT        WRITE          WRITE"         READ           READ"          CLOSE          DEL"
 227
 228 BOOTLOADER adds a boot on SD_CARD
 229
 230     (QUIT)         BOOT
 231
 232 VOCABULARY to create vocabularies (words list)
 233
 234     DEFINITIONS    ONLY           PREVIOUS       ALSO           FORTH          VOCABULARY
 235
 236
 237
 238 ADDs-ON below may be added either hard in kernel or later loaded/removed as any application:
 239
 240 ANS\_CORE\_COMPLIANT necessary to pass ANS94 CORE tests
 241
 242     >BODY          SOURCE         .(             (              DECIMAL        HEX            FILL           +!
 243     [CHAR]         CHAR           CELL+          CELLS          CHAR+          CHARS          ALIGN          ALIGNED
 244     2OVER          2SWAP          2DROP          2DUP           2!             2@             */             */MOD
 245     MOD            /              /MOD           *              FM/MOD         SM/REM         UM/MOD         M*
 246     UM*            S>D            2/             2*             MIN            MAX            1-             1+
 247     RSHIFT         LSHIFT         INVERT         {ANS_COMP}
 248
 249 SD\_TOOLS, basic tools for FAT16/32
 250
 251     DIR            FAT            CLUSTER        SECTOR         {SD_TOOLS}
 252
 253 FIXPOINT, minimalist fixed point arithmetic + - * /
 254
 255     2CONSTANT      D>F            S>F            F.             F*             F#S            F/             F-
 256     F+             HOLDS          {FIXPOINT}
 257
 258 UTILITY:
 259
 260     DUMP           U.R            WORDS          ?              .RS            .S             {UTILITY}
 261
 262
 263
 264
 265 Organize your gitlab copy of FastForth
 266 -------
 267
 268 download zip of last version
 269
 270 copy it to a subfolder, i.e. FastForth, created in your user folder
 271
 272 right clic on it to share it with yourself.
 273
 274 remember its shared name i.e. : //myPC/users/my/FastForth.
 275
 276 in file explorer then right clic on root to connect a network drive, copy shared name in drive name and choose a free drive letter a:, b: ...
 277
 278 Thus all relative paths will be linked to this drive, except the three \MSP430-FORTH\files.bat links.
 279 For all of them right clic select, select properties then check drive letter in target.
 280
 281 WARNING! if you erase a file directly in this drive or in one of its subfolders, no trash, the file is lost!
 282
 283
 284
 285 Minimal Software
 286 --
 287
 288 If you are under WINDOWS :
 289
 290         First, you download the TI's programmer from TI : http://www.ti.com/tool/MSP430-FLASHER.
 291         And the MSP430Drivers :
 292         http://software-dl.ti.com/msp430/msp430_public_sw/mcu/msp430/MSP430_FET_Drivers/latest/index_FDS.html
 293
 294         The next tool is TERATERM.EXE : http://logmett.com/index.php?/products/teraterm.html.
 295
 296         As scite is my editor, this github repository is fully configured for scite users.
 297     download the single file executable called sc1 (not the full download! ) :
 298     http://www.scintilla.org/SciTEDownload.html, then save it as \prog\wscite\scite.exe.
 299
 300         download GEMA preprocessor : https://sourceforge.net/projects/gema/files/gema/gema-1.4-RC/
 301
 302         The MacroAssembler AS : http://john.ccac.rwth-aachen.de:8000/as/
 303
 304         and Srecord : http://srecord.sourceforge.net/download.html to convert HEX file to TI TXT files.
 305
 306         copy last 3 items onto their respective \prog subfolder.
 307
 308         ask windows to open .asm, .inc, lst, .mac, .4th, .f, .pat files with scite.exe
 309
 310
 311 If you are linux or OS X men, try virtualbox...
 312
 313
 314 Build the program file
 315 ----------------------
 316
 317
 318 \forthMSP430FR.asm is the main file to compile FastForth. It calls :
 319
 320         - mspregister.mac that defines the TI symbolic instructions,
 321         - Target.inc that defines for each device the eUSCI used as Terminal
 322           and then selects the declarations file family.inc,
 323         - ForthThreads.mac in case of multithread vocabularies,
 324         - optionally, forthMSP430FR_SD.asm file(s) for SD_Card,
 325         - optionally, forthMSP430FR_ASM.asm for assembler,
 326         - TargetInit.asm that selects the target.asm,
 327         - and then TERMINALBAUDRATE.asm.
 328
 329 open it with scite editor
 330
 331 uncomment the target as you want, i.e. MSP_EXP430fr5969
 332
 333 choose frequency, baudrate, UART handshake.
 334
 335 uncomment options switches as your convenience.
 336
 337 save file.
 338
 339 assemble (CTRL+0). A window asks you for 4 parameters:
 340
 341 set device as first param, i.e. MSP_EXP430FR5969,
 342
 343 then execute. the output is a target.txt file, i.e. MSP_EXP430FR5969.txt
 344
 345
 346
 347 Load Txt file (TI format) to target
 348 -----------------------------------
 349
 350         drag your target.txt file and drop it on TARGETprog.bat
 351
 352     or use scite internal command TOOLS:FET prog (CTRL+1).
 353
 354 nota : programming the device use SBW2 interface, so UART0 is free for serial terminal use.
 355
 356 If you want to program your own MSP430FRxxxx board, wire its pins TST, RST, 3V3 and GND to same pins of the launchpad, on eZ-FET side of the programming connector.
 357
 358
 359
 360 Connect the FAST FORTH target to a serial terminal
 361 -------------------------------------------------
 362
 363 you will need an USBtoUART cable with a PL2303TA or PL2303HXD device that allows both XON/XOFF and hardware control flow :
 364
 365         http://www.google.com/search?q=PL2303TA
 366         http://www.google.com/search?q=PL2303HXD
 367     WARNING! XON/XOFF no longer works with new Prolific driver v3.8.12.0 (03/03/2017)...
 368              Waiting next update, get on web previous PL2303_Prolific_DriverInstaller_v1160.exe (or .zip)
 369
 370
 371 or USBtoUART bridge, with a CP2102 device and 3.3V/5V that allows XON/XOFF control flow :
 372
 373         search google: cp2102 module 3.3V
 374         http://www.silabs.com/products/mcu/Pages/USBtoUARTBridgeVCPDrivers.aspx
 375
 376     you must program CP2102 device to access 1382400 and 1843200 bds rates :
 377         http://www.silabs.com/Support%20Documents/Software/install_USBXpress_SDK.exe
 378         http://www.silabs.com/Support%20Documents/TechnicalDocs/an169.pdf
 379
 380 or a USBtoUART bridge, with a FT232RL device and 3.3V/5V for only hardware control flow:
 381
 382     WARNING! buy a FT232RL module with a switch 5V/3V3 and select 3V3.
 383
 384         http://www.google.com/search?q=FT232RL+module+3.3V
 385         http://www.ftdichip.com
 386
 387
 388 How to configure the connection ?
 389 -------------------------------
 390
 391 1-    XON/XOFF control flow: Launchpad UARTn  <--> USBtoUART bridge with cp2102|PL2303TA/HXD chipset <--> TERATERM
 392
 393        UARTn <--> UART2USB
 394          TXn ---> RX
 395          RXn <--- TX
 396         (GND <--> GND)
 397                 WARNING! DON'T CONNECT 5V RED WIRE!
 398
 399       TeraTerm configuration : see DTCforthMSP430fr5xxx.asm
 400
 401 If you plan to supply your target vith a PL2303 cable, open its box to weld red wire onto 3.3V pad.
 402
 403 2-    hardware control flow: Launchpad UARTn <--> USBtoUART bridge with FT232RL or PL2303TA/HXD <--> TERATERM
 404
 405        UARTn <--> UART2USB
 406          TXn ---> RX
 407          RXn <--- TX
 408          RTS ---> CTS
 409         (GND <--> GND)
 410                 WARNING! select 3V3 !
 411                 WARNING! DON'T CONNECT 5V !
 412
 413       TeraTerm configuration : see DTCforthMSP430fr5xxx.asm
 414
 415
 416 Send a source file to the FAST FORH target
 417 ------------------
 418
 419 Three .bat files are done in \MSP430-FORTH that enable you to do all you want.
 420 Double clic on them to see how to do.
 421
 422 you can also open any source file with scite editor, and do all you want via its Tools menu.
 423
 424
 425 SD_Card Load, Read, Write and Delete
 426 =============================================
 427
 428 First, hardware
 429 ---------------
 430
 431 If you have MSP-EXP430FR5994, nothing to do.
 432
 433 For the choice of a SD card socket be carefull, pin CD (Card Detect) must be present! google search: "micro SD card 9 pin"
 434
 435
 436 the commands
 437 ------------
 438
 439 With the LOAD" pathame" command you load your source files from a SD_CARD memory in both execute and compile modes. Idem for READ", WRITE" and DEL" commands.
 440
 441 See "SD_TESTS.f", a FORTH program done for example
 442
 443 If you remove the SD memory card reader and then reset, all SD\_IO pins are available except SD_CD obviously.
 444
 445 HowTo LOAD a sourcefile
 446 --------------
 447
 448         LOAD" path\filename.4th".
 449
 450 The file is interpreted by FORTH in same manner than from the serial terminal.
 451
 452 When EOF is reached, the file is automatically closed.
 453
 454 A source file can _LOAD"_ an other source file, and so on in the limit of available handles (up to 8).
 455
 456 HowTo READ a file
 457 --------------
 458
 459         READ" path\filename.ext".
 460
 461 The first sector of this file is loaded in BUFFER.
 462 To read next sectors, use the command READ that loads the next sector in the buffer, and leaves on the stack a flag that is true when the EOF is reached.
 463 The file is automatically closed. See tstwords.4th for basic usage.
 464
 465 The variable BufferLen keep the count of bytes to be read (0 to 512).
 466
 467 If you want to anticipate the end, use the CLOSE command.
 468
 469 HowTo WRITE a file
 470 ---------------
 471
 472         WRITE" path\filename.ext".
 473
 474 If the file does not exist, create it, else open it and set the write pointer at the end of the file, ready to append chars.
 475
 476 See example of use in \MSP430-FORTH\SD_TEST.f.
 477
 478 To overwrite an existing file: DEL" file" then  WRITE" file".
 479
 480 Use CLOSE to close the file.
 481
 482 HowTo delete a file
 483 ---------------
 484
 485         DEL" path\filename.ext". If the file is not found, do nothing, no error.
 486
 487 HowTo change DIRectory
 488 ---------------
 489
 490         LOAD" \misc".               \misc becomes the current folder.
 491         LOAD" ..\"                      parent folder becomes the current folder.
 492         LOAD" \"                                Root becomes the current folder.
 493
 494 Drive letters are always ignored.
 495
 496 Downloading source file to SD_Card
 497 ------------------------------------------
 498
 499 to download a source file (.f or .4th) onto SD_CARD target, use CopySourceFileToTarget_SD_Card.bat.
 500 or use scite.
 501 Double click on one of this bat files to see how to do.
 502
 503
 504 I2C DRIVERS
 505 ===========
 506
 507 The I2C\_Soft\_Master driver with normal/fast mode allows you to add then use any couple of pins to drive a bus I2C :
 508
 509  - without use of eUSCI UCBx
 510  - I2C\_Soft\_MultiMaster driver : same plus detection collision
 511  - plus I2C\_Slave driver that uses the eUSCI UCBx hardware
 512
 513
 514 Other interesting specificities :
 515 =====
 516
 517 Management of vocabularies (not ANSI). VOCABULARY, DEFINITIONS, ONLY, ALSO, PREVIOUS, CONTEXT, CURRENT, FORTH, ASSEMBLER.
 518 In fact, it's the the assembler that requires the vocabularies management.
 519
 520 Recognizing prefixed numbers %101011 (bin), $00FE (hex) and #220 (decimal).
 521
 522 CAPS ON/OFF add on
 523
 524 ECHO / NOECHO
 525
 526 The words DEFER and IS are implemented. CR, EMIT, KEY, ACCEPT, QUIT and WARM are deferred words.
 527
 528 Error messages are colored (reverse video on ANSI terminal).
 529
 530 Assembly jumps are as FORTH one's : IF, ELSE, THEN, BEGIN, AGAIN, UNTIL, WHILE.
 531 Not canonical jumps are also available with JMP|?JMP to a defined word and GOTO|?GOTO to backward labels BW1 BW2 BW3 or forward labels FW1 FW2 FW3.
 532 These labels are for one use.
 533 Switch  within definitions between FORTH and Assembly contexts with words HI2LO and LO2HI. See examples in the TstWords.f file. This is perhaps the most interesting feature for development...
 534
 535
 536 The system is not responding ?
 537 ======
 538
 539 First, swich off then switch on. FORTH restarts as it was after the last PWR\_HERE command.
 540
 541 If the system is not restarted, press <reset> button on the MSP-EXP430FR5xxx ; FORTH restarts as it was after the last RST_HERE command.
 542
 543 If the system does not restart again, wire the TERMINAL TX pin to GND via 4k7 resistor then <reset> ; FORTH restarts as it is in the HEX file.
 544 Equivalent word : COLD + WIPE.
 545
 546 Here is the FastForth init architecture :
 547
 548         case 0 : when you type WARM, FORTH interpreter is restarted, no program lost.
 549                          if ECHO is on, the WARM display is preceded by "0", else no display.
 550
 551         case 1 : Power ON ==> performs reset and the program beyond PWR_HERE is lost.
 552                          if ECHO is on, the WARM display is preceded by the SYSRSTIV value "2", else no display.
 553
 554         case 1.1 : when you type PWR_STATE ==> the program beyond PWR_HERE is lost.
 555
 556         case 1.2 : If an error message (reverse video) occurs, PWR_STATE is automatically executed and the program beyond
 557                PWR_HERE is lost. In this way, any compilation error is followed by the complete erasure of the
 558                uncompleted word, or by that of the downloading source file causing this error.
 559                So, it is recommended to finish a source file with at least PWR_HERE to protect it against any
 560                subsequent error.
 561
 562         case 2 : <reset>  ==> performs reset and the program beyond RST_HERE is lost.
 563                          if ECHO is on, the WARM display is preceded by the SYSRSTIV value "4", else no display.
 564
 565         case 2.1 : when you type COLD (software reset) ==> same effects.
 566                            if ECHO is on, the WARM display is preceded by the SYSRSTIV value "6", else no display.
 567
 568         case 2.2 : when you type RST_STATE ==> the program beyond RST_HERE is lost.
 569
 570
 571         case 3 : when you type WIPE ==> all programs donwloaded from the terminal or the SD_Card are lost.
 572
 573
 574         case 4 : TERM_TX wired to GND via 4k7 during <reset> = DEEP_RST ===> performs reset, and all programs donwloaded
 575              from the terminal or the SD_Card are lost. The WARM display is preceded by "-4".
 576
 577         case 4.1 : software reset on failure (SYSRSTIV = 0Ah | SYSRSTIV >= 16h) ===> same effects
 578                            The WARM display is preceded by the SYSRSTIV value.
 579
 580         case 4.2 : writing -1 in SAVE_SYSRSTIV before COLD = software DEEP_RST ===> same effects
 581                            The WARM display is preceded by "-1".
 582
 583         case 5 : after FAST FORTH core compilation, the WARM displays SAVE_SYSRSTIV = 3. User may use this information
 584              before WARM occurs.
 585
 586
 587 If SD\_CARD extention and SD\_CARD memory with \BOOT.4TH included, the cases 1 to 4 start it after displaying of WARM message.
 588
 589
 590 EMBEDDED ASSEMBLER
 591 ======
 592
 593 With the preprocessor GEMA and the file MSP430FR\_FastForth.pat, the embedded assembler allows access to all system variables. See \\config\\gema\\MSP430FR\_FastForth.pat. You can also access to VARIABLE, CONSTANT or DOES type words in immediate (#), absolute (&) and indexed (Rx) assembly modes.
 594
 595 Clearly, after the instruction "MOV &BASE,R6", R6 equals the contents of the FORTH variable "BASE", and after "MOV #BASE,R6" R6 contains its address.
 596
 597 If you want to create a buffer of 8 bytes (4 words) :
 598
 599         CREATE BUFFER_OUT 8 ALLOT
 600 the access to this buffer is done by :
 601
 602         MOV #BUFFER_OUT,R8
 603         MOV.B @R8,R9
 604 with R8 as org address of the buffer.
 605
 606 Or by indexed addressing :
 607
 608         MOV.B BUFFER_OUT(R8),R9
 609 with R8 register as buffer pointer.
 610
 611 see \MSP430-FORTH\TESTASM.4th.
 612
 613 What is the interest of a very fast baud rate ?
 614 ---------------------
 615
 616 This seems obvious: you can edit a source program and then test it immediatly on the target: above, from my text editor, the download, compile and start are done in less than 1 sec.
 617
 618 VOCABULARY ADD-ON
 619 ====
 620
 621 These words are not ANS94 compliant, they are those of F83 standard.
 622
 623 For example, after loading SD_TOOLS add-on, you can type: ALSO ASSEMBLER WORDS PREVIOUS WORDS
 624
 625     With ALSO ASSEMBLER, the vocabulary ASSEMBLER is added to the search CONTEXT thus the ASSEMBLER words become visible
 626
 627     WORDS display the words of ASSEMBLER then those of FORTH,
 628
 629     PREVIOUS remove the vocabulary ASSEMBLER form the CONTEXT, and the ASSEMBLER words become hidden,
 630
 631     so the last WORDS display only FORTH words.
 632
 633 In the forthMSP430FR_ASM.asm, see the FORTH word CODE that add ASSEMBLER to the search CONTEXT and the ASSEMBLER word ENDCODE
 634  that remove ASSEMBLER from search CONTEXT. Thus, the assembler words can be used only between CODE and ENDCODE.
 635
 636 The CONTEXT can grow up to 6 vocabularies by using the word ALSO.
 637
 638 If you want add words to the assembler you must type: ALSO ASSEMBLER DEFINITIONS,
 639 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.
 640
 641 Finally, FORTH ONLY DEFINITIONS limits the search CONTEXT to FORTH and the CURRENT vocabulary is FORTH.
 642
 643