README.md

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