README.md

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