README.md

   1 ## FastForth for MSP430FRxxxx TI's CPUs, light, fast, reliable.
   2
   3
   4 Tested on TI MSP-EXP430FR
   5 [5739](https://duckduckgo.com/?q=MSP-EXP430FR5739&iax=images&ia=images),
   6 [**5969**](https://duckduckgo.com/?q=MSP-EXP430FR5969&iax=images&ia=images),
   7 [**5994**](https://duckduckgo.com/?q=MSP-EXP430FR5994&iax=images&ia=images),
   8 [6989](https://duckduckgo.com/?q=MSP-EXP430FR6989&iax=images&ia=images),
   9 [4133](https://duckduckgo.com/?q=MSP-EXP430FR4133&iax=images&ia=images),
  10 [2476](https://duckduckgo.com/?q=LP-MSP430FR2476&iax=images&ia=images),
  11 [**2355**](https://duckduckgo.com/?q=MSP-EXP430FR2355&iax=images&ia=images),
  12 [2433](https://duckduckgo.com/?q=MSP-EXP430FR2433&iax=images&ia=images) launchpads, at 1, 2, 4, 8, 12, 16 MHz plus 20 & 24 MHz with MSP430FR(23xx,57xx) devices.
  13
  14
  15 note: if you want to write a program to make a LED flash, i suggest you to go [here](https://www.raspberrypi.com),
  16       but if you want to deepen your programming basics, you've come to the right place.
  17
  18 FastForth is a "Just In First" Load-Interpret-Compile Operating System for all the 16/20 bits CPU MSP430FRxxxx (MSP430 with FRAM) :
  19
  20 * LOAD: choice of the TERMINAL interface:
  21
  22     * UART TERMINAL up to 6MBds @ MCLK=24MHz, with software (XON/XOFF) or hardware (RTS) control flow, **transmit delay: 0 ms/char, 0 ms/line**
  23
  24     * a very well designed **I2C TERMINAL**, with a full duplex behaviour, ready to communicate with all the targets **I2C_FastForth** wired on its I2C bus,
  25
  26 * INTERPRET: with a 16-entry word-set that speeds up the FORTH interpreter by 4,
  27
  28 * COMPILE: in addition to the FORTH engine, the **MSP430 assembler, label free, with the TI's syntax** (not the FORTH one!),
  29
  30 and as result "Load Interpret Compile" a source file is faster and easier than **just** loading its equivalent TI.txt binary file via the TI's eZFET interface.
  31 For example, with a target running at 24MHz, UART=6MBds 8n1, an USBtoUART bridge [PL2303GC](https://duckduckgo.com/?q=DSD+TECH+SH-U06A)
  32 and [Teraterm.exe](https://osdn.net/projects/ttssh2/releases/) as TERMINAL,
  33 the "JIF" process of the /MSP430-FORTH/CORETEST.4TH file is done at an **effective rate** up to 800 kBds, up to 500 kBds with an I2C_Slave target running at 24MHz, and beyond 1Mbit/s from a SD_CARD.
  34 This is, by far, unparalleled on the planet FORTH, and on others too.
  35
  36 Despite its **size of 4.75 kb** FastForth includes:
  37
  38 * FORTH kernel with interpreting decimal, hex, binary (#,$,% prefixed) numbers, digits separator '_', 'char', double numbers and Q15.16 numbers,
  39
  40 * the assembler for MSP430 (with TI's syntax),
  41
  42 * a good error handling which discards the "JIF" process of source files and thus avoids system crash,
  43
  44 * a memory management which can be modulated according to these 3 levels (software|hardware): `-1 SYS`|`<SW1+RST>`, `MARKER`|, `6 SYS`|`<RST>`.
  45
  46 * everything you need to write a real time application:
  47
  48     * the complete set of the FORTH building definitions,
  49
  50     * conditional compilation,
  51
  52     * thanks to [GEMA preprocessor](http://gema.sourceforge.net/new/index.shtml), the compilation of all symbolic addresses without having to declare them in FORTH,
  53
  54     * easy roundtrip between FORTH and ASSEMBLER levels with only two 'one word' switches: `HI2LO`, `LO2HI`,
  55
  56     * automatic releasing memory with `MARKER` and `RST_SET`/`RST_RET` tags,
  57
  58     * Fully configurable sequences reset, init and background,
  59
  60     * CPU in sleep mode LPM0|LPM4 in awaiting a command from UART|I2C TERMINAL, and ready to process any interrupts.
  61
  62 If you want to quickly get an idea of what Fast Forth can do, see the /MSP430-FORTH/UARTI2CS.f application file.
  63 You will see that the FORTH language is used here as packaging of the program written in assembler.
  64 See /MSP430-FORTH/FF_SPECS.f for another point of view.
  65
  66 For only 3 kb in addition, we have the primitives to access the SD_CARD FAT32: read, write, del, download source files and also to copy them from PC to the SD_Card.
  67 It works with all SD\_CARD memories from 4GB to 64GB with FAT32 format.
  68
  69 With all the kernel addons, including the 20 bits MSP430\_X assembler and the SD\_Card driver, FastForth size is **10 kB**.
  70
  71 Once downloading /MSP430-FORTH/CORE_ANS.f file (2.25 kb), FastForth passes the tests: /MSP430-FORTH/CORETEST.4TH ( CORE ANS94 + COREPLUSTEST ), thus proving its compliance with the ANS94 standard.
  72
  73 However, if all works well with Windows 10, it works less well with Linux due to the lack of a good alternative to TERATERM...
  74
  75 Note: please, for each update download all subdirectories to correctly update the project.
  76
  77 ## how to connect TERMINAL
  78
  79     The files \binaries\launchpad_xMHz.txt are the executables ready to use with a serial terminal
  80     (TERATERM.exe), with XON/XOFF or RTS_hardware flow controls and a PL2303TA/CP2102 cable.
  81     ------------------------------------------------------------------------------------------
  82     WARNING! doesn't use it to supply your launchpad: red wire is 5V ==> MSP430FRxxxx destroyed!
  83     ------------------------------------------------------------------------------------------
  84     (modify this first: open the box and weld red wire on 3.3V pad).
  85
  86 ### programming with MSP430Flasher/UniFlash and FET interface:
  87
  88             J101 connector
  89                     |
  90                     v
  91      TI Launchpad <--> FET interface  <-------------> USB <-------->COMx<----> MSP430Flasher.exe/UniFlash
  92               Vcc <--- 3V3
  93        TST/SBWTCK <--> SBWTCK        )
  94               GND <--> GND           > used to program MAIN
  95       RST/SBWTDIO <--> SBWTDIO       )
  96
  97      TI Launchpad <--> CP2102/PL2303 cable <--------> USB <-------->COMy<----> TERATERM.exe
  98                RX <--- TX            )
  99               GND <--> GND           > FastForth TERMINAL
 100                TX ---> RX            )
 101      Pin Px.y RTS ---> CTS (optionnal) RTS pin Px.y is described in your \inc\launchpad.asm)
 102
 103     TERATERM config terminal:   NewLine receive : LF,
 104                                 NewLine transmit : CR+LF
 105                                 Size : 80 chars x 42 lines (adjust lines according to your display)
 106                                 type terminal : VT520
 107
 108     TERATERM config serial port:    COM = these of your USBtoUART device
 109                                     speed = TERMINALBAUDRATE value,
 110                                     8 bits, no parity, 1 Stop bit,
 111                                     XON/XOFF flow control,
 112                                     delay = 0ms/line, 0ms/char
 113
 114     **don't forget to save always new TERATERM configuration !**
 115
 116 ## Out of the box
 117
 118 Once FastForth is loaded in the target FRAM memory, you add assembly code or FORTH code, or both,
 119 by downloading your source files which embedded FastForth interprets and compiles.
 120
 121 Beforehand, the preprocessor GEMA, by means of a \config\gema\target.pat file, will have translated
 122 your generic MSP430FR.f source file in a targeted MSP430FRxxxx.4th source file, allowing you to use
 123 symbolic addressing for all peripheral registers (SFR), without having to do FORTH declarations.
 124 A set of .bat files in \MSP430-FORTH folder is furnished to do all this automatically.
 125
 126 To see all specifications of FastForth, download \MSP430-FORTH\FF_SPECS.f.
 127
 128 To change the UART TERMINAL baudrate on the fly, 9600 Bauds up to 6 MBds, download \MSP430-FORTH\CHNGBAUD.f.
 129 Beyond 1 MBds, shorten the PL2303HXD cable, down to 50 cm for 6MBds.
 130
 131 XON/XOFF flow control allows 3.75kV galvanic isolation of terminal input with SOIC8 Si8622EC|ISO7021.
 132
 133 If you choose I2C_FastForth for your project, you will need of one more launchpad to make the UARTtoI2C bridge.
 134 See driver for it :  \MSP430-FORTH\UARTI2CS.f.
 135
 136 Notice that FAST FORTH interprets lines up to 84 chars, only SPACE as delimiter, only CR+LF as
 137 End Of Line, and BACKSPACE; all other control chars are discarded.
 138 And that the high limit of a FORTH program memory is $FF40.
 139
 140 Finally, using the SCITE editor as IDE, all is ready to do everything from its "tools" menu.
 141
 142 What is new ?
 143 -------------
 144
 145 ### V4.1, the last.
 146
 147 * = V4.0 - 10 bytes.
 148
 149 * the pack of \inc\files.pat, used by GEMA.EXE to convert a generic FORTH file.f to a customised FORTH file.4TH, is simplified:
 150     * MSP430FRxxxx.pat for FRAM(INFO TLV MAIN) declarations,
 151     * MSP430FR5xxx.pat, MSP430FR57xx.pat and MSP430FR2xxx.pat for RAM declarations,
 152     * \<target\>.pat and \<device\>.pat for target and device configurations.
 153
 154 * rewritten bat files.
 155
 156 * WARM now displays a number which includes the error codes SYSUNIV (7) and SYSSNIV (15), in addition to SYSRSTIV ones (31)
 157
 158 * fixed `>NUMBER`
 159
 160 * SD_TEST.4TH used as SD_CARD bootstrap on reset (or not) works fine, just for my 68th birthday!
 161
 162 ### V4.0, the penultimate last.
 163
 164 * = V3.9 - 26 bytes.
 165
 166 * `HNDCODE` and `TICK` fixed
 167
 168 * `KEY` and `EMIT` rewritten, also `ECHO` and `NOECHO`
 169
 170 * the assembler handles correctly argument+/-offset
 171
 172 * the SD_Card driver is re-rewritten
 173
 174     * it only supports FAT32 format and SD Cards from 4 GB to 64 GB
 175
 176     * FAT32 Directories can be enlarged
 177
 178     * fixed errors handling
 179
 180 * the driver UART to I2C is enhanced and more reliable
 181
 182 * added DOUBLE.asm in /ADDONS (DOUBLE word set)
 183
 184
 185 ### V3.9
 186
 187 * = V3.8 - 350 bytes.
 188
 189 * removed `INTERPRET`, `CR` and the useless error line displaying.
 190
 191 * Removed `PWR_HERE` and `PWR_STATE`, replaced `RST_HERE` by `RST_SET` and `RST_STATE` by `RST_RET`.
 192
 193 * Replaced `WIPE` by `-1 SYS`, `COLD` by `4 SYS` and `WARM` by `0 SYS` or simply `SYS`.
 194
 195 * replaced `VOCABULARY` with `WORDSET`. `ALSO` is removed because the executing of a definition created by `WORDSET` adds it into the CONTEXT stack. For example, typing `FORTH` adds it into CONTEXT. Note that as result the use of ONLY is modified: `FORTH ONLY` instead of ~~`ONLY FORTH`~~.
 196
 197 * modified QNUMBER QABORT `ABORT` `QUIT` `HI2LO` `PREVIOUS` `WORD` `FIND` `>NUMBER` `TYPE` `#>` `COUNT` `SWAP` `TICK` `POSTPONE` `COLON` `[ELSE]` plus the assembler.
 198
 199 * The bootstrap ON/OFF is modified: `BOOT` / `NOBOOT` to enable / disable it.
 200
 201 * the word-set `ASSEMBLER` is renamed `hidden` because it stores not only the ASM instructions definitions but also HDNCODE definitions.
 202
 203 * when you execute a `MARKER` definition, it starts by removing from its previous definition if exists.
 204
 205 * Some bugs corrected:
 206     * QNUMBER FORWDOES `TYPE` `WORD`,
 207     * `M*/` in \MSP430-FORTH\DOUBLE.f file,
 208     * ~~the assembler handles correctly argument+/-offset.~~
 209
 210 * User can choose floored or symmetric division. See \MSP430-FORTH\ANS_CORE.f
 211
 212 * the words `:NONAME` `IS` `DOES>` `CODENNM` are added to the core and there is still enough room in its 5kb for the VOCABULARY_SET add-on.
 213   DEFER is not included because too easy to replace by a CODE definition, see CR in file CORE_ANS.f.
 214
 215 * When used with VOCABULARY_SET activated, `RST_SET`/`RST_RET` and definition/use of `MARKER` tags save/restore the full word-set environment: DP, CURRENT, CONTEXT stack, VOCLINK.
 216
 217 * FF_SPECS.f displays all word-sets, including the `hidden` one.
 218
 219 * the SD_Card driver is rewritten. Only FAT32 format is supported. I suggest 4kb sized clusters.
 220   The old `WRITE"` command is duplicated :
 221     * `WRITE"` to create a new file (to overwrite if found),
 222     * `APPEND"` to append to a file (to create it if not found)
 223
 224
 225 ### V3.8
 226
 227 * = V3.7 - 16 bytes.
 228
 229 * Source file copy from TERMINAL to the SD\_Card of any I2C\_FastForth target works fine.
 230
 231 * ~~The bootstrap call is modified: `' BOOT IS WARM` to enable it, `' BOOT [PFA] IS WARM` to remove it~~.
 232
 233 * `ASM` definitions are renamed `HDNCODE` (HiDdeN CODE), `ENDASM` is replaced by `ENDCODE`.
 234
 235     `HDNCODE` definitions are identical to low level `CODE` ones, but are hidden because defined in the ~~`ASSEMBLER`~~ `hidden` word set, and must be used only
 236     in the scope of another low level CODE definition. See use in \MSP430-FORTH\UARTI2CS.f.
 237
 238 * FastForth passes CORETEST + COREPLUSTEST tests. See modified \MSP430-FORTH\CORETEST.4TH
 239
 240 * Double number word `D<` corrected in \MSP430-FORTH\DOUBLE.f
 241
 242
 243 ### V3.7
 244
 245 * 54 bytes added to (Kernel + Conditional_Compilation + Assembler).
 246
 247 * ~~Source file copy from I2C_TERMINAL to the SD_Card of any I2C_target works now.~~
 248
 249 * In addition of target's ID test made by Teraterm macro, a preamble has been added to all
 250     \MSP430-FORTH\source.f files to prohibit their downloading with another version of FastForth.
 251
 252 * Words @ ! ALLOT come back from "ANS_COMP" add-on to core.
 253
 254 * Recognized prefixes are $ # % and ' respectively for hex decimal binary and ASCII 'char' numbers.
 255     Examples: 'U' - $55 = 0, '3' - #33 = 0, '@' - %0100_0000 = 0.
 256     When use in source.f files, all ASCII special chars are available. See \inc\FastForthREGtoTI.pat.
 257
 258 * Assembler allows "argument+offset" into FORTH area (0 to $FFFF). Examples:
 259  `MOV #RXON,&BACKGRND+2` to store RXON addr at BACKGRND+2 addr.
 260  `MOV.B BUFFER-1(X),TOS` to load the byte at BUFFER-1(X) addr in the register TOS.
 261
 262 * `6 SYS` does same than hardware RST.
 263   `-1 SYS` does same than hardware SW1+RST (DEEP_RESET).
 264
 265
 266 * More complicated:
 267
 268   In the FastForth init process, COLD WARM ABORT" BACKGRND are modified and INIT_FORTH is added.
 269   They include each a call to a paired assembly subroutine:
 270
 271           RST_SYS failures ------------>+       +<----------<display error>----- ABORT" <---+<-- COMPILE/EXECUTE<-INTERPRET <--+
 272                                         |       |                                =====      |                                  ^
 273           RST ----------->+             |       v                                           v                                  |
 274                           v             |       +-> INIT_FORTH ----------->+-> ABORT->QUIT->+->ACCEPT->+            +->ACCEPT->+
 275           SW1+RST ------->+             |           ==========             ^                           |            ^
 276                           v             v                                  |                           v            |
 277           -n SYS -------->+---> COLD -->+->PUC->+-> INIT_FORTH --> WARM -->+                           +->BACKGRND->o
 278                           ^     ====            ^   ==========     ====                                   ========  ^
 279                           |                     |                                                                   \
 280           +n SYS (even) ->+                     |                                                                   /
 281                                                 |                                                                   \
 282           +n SYS (odd) -->+--> (NOPUC) -------->+                                                        UART_RX_INT/I2C_START_INT
 283                           ^     ====
 284           [0] SYS ------->+
 285
 286                       CALL...   &STOP_APP          &SOFT_APP    &HARD_APP       &ABORT_APP               &BACKGRND_APP
 287                                 =========          =========    =========       ==========               =============
 288
 289            Default subroutine   INIT_STOP          INIT_SOFT    INIT_TERM       ABORT_TERM               INIT_BACKGRND
 290                Default action   UART: wait idle    do nothing   init TERM UC..  discard..                UART: send RXON
 291                                 I2C: do nothing                 ..unlock I/O    ..downloading            I2C: send Ctrl_Char $00
 292
 293           note: -n SYS|SW1+RST reset the default subroutine of these five calls.
 294                 don't use TOS in these subroutines.
 295
 296     On the other hand, MARKER is modified in such a way that MARKER\_DOES executes a CALL to
 297     the content of USER_PARAM-2,   by default RET_ADR:
 298
 299         MARKER [CFA]         = DODOES
 300                [PFA]         = MARKER_DOES
 301                [BODY]        = previous DP (Dictionnary Pointer)
 302                ...
 303                [USER_PARAM-2] = RET_ADR  as REMOVE_APP by default
 304
 305
 306 By replacing [USER_PARAM-2] with the address of a new defined subroutine (named for example: REMOVE_XXX),
 307 MARKER_DOES will execute it to restore n critical pointers (room made by 2n ALLOT) at USER_PARAM, USER_PARAM+2, ...
 308
 309 Thus, with MARKER and the definition of some subroutines according to the need: STOP_XXX, SOFT_XXX, HARD_XXX, ABORT_XXX, BACKGRND_XXX,
 310 the programmer has full control of his "XXX" real time application using interrupts,
 311 with everything he needs to start, stop and remove it properly, thanks to this 'soft' MARKER definition,
 312 avoiding the hardware (SW1+RST) of the last chance.
 313
 314 See example in  /MSP430-FORTH/UARTI2CS.f.
 315
 316
 317 ### V3.6
 318
 319 * 8 bytes added to (Kernel + Conditional_Compilation + Assembler).
 320
 321 * Fixed the crash caused by forgetting the prefix '&' in the last term of an assembly instruction.
 322     (the TI's symbolic mode is not implemented).
 323
 324 * Added in the macro \config\SendFile.ttl the word ?ID to prevent any crash during download
 325     due to a device confusion:
 326
 327    when downloading a source_file.f asked from the scite editor or by the use
 328    of SendSourceFileToTarget.bat, Teraterm macro first sends ?ID definition then
 329    the string:  %deviceID% ?ID.
 330    By executing ?ID, FastForth substracts %deviceID% value from the target's one then
 331    executes ABORT" DeviceID mismatch!" : the downloading is aborted if DeviceID mismatch.
 332    %deviceID% is provided by the file \config\select.bat.
 333
 334    When downloading a source_file.4TH, it's up to you to be careful because
 335    Teraterm sends the string 0 ?ID, so that ?ID bypasses the substraction.
 336
 337 * Added the word set DOUBLE in the \MSP430-FORTH\DOUBLE.f file.
 338
 339 ### V3.5
 340
 341 * 48 bytes removed.
 342
 343 * from Scite menu, we can program MSP430FRxxxx also with BSL_Scripter.
 344
 345     To do, save file \prog\BSL_Scripter.exe from:
 346     https://github.com/drcrane/bslscripter-vs2017/releases/download/v3.4.2/BSL-Scripter-v3.4.2.zip,
 347     but erasing a MSP430FR2355 or MSP430FR2476 doesn't work, thanks to BSL V. 00.09.36.B4 & B5.
 348     See SLAU550Z tables 16 & 17.
 349
 350     and buy a USB2UART module CP2102 6 pin. On the web, search: "CP2102 3.3V DTR RTS"
 351     For wiring, see \config\BSL_Prog.bat.
 352
 353     So, we download both binaries and source files with only one CP2102|PL2303TA module,
 354     the XON/XOFF TERMINAL and BSL_Scripter. Bye bye T.I. FET!
 355
 356 * ABORT messages display first the I2C address, if applicable.
 357
 358 * QNUMBER some issues solved.
 359 * UART version of ACCEPT and KEY are shortened.
 360 * EVALUATE is moved to CORE_ANS.
 361
 362 ### V3.4
 363
 364 * 36 bytes removed.
 365
 366 * Fixed: word F. issue in FIXPOINT.asm
 367
 368 * the new kernel DEFERRED option adds :NONAME CODENNM DEFER IS.
 369
 370 * pin RESET is software replaced by pin NMI and so, RESET executes COLD, allowing code insert before BOR.
 371   however SYSRSTIV numbering remains unchanged: = 4 for RESET, = 6 for COLD.
 372
 373 * Hardware Deep RESET (S1+RST) reinitializes vectors interrupts and SIGNATURES area, as WIPE.
 374
 375
 376 * A newcomer: FastForth for I2C TERMINAL. With the driver UART2I2CS running on another FastForth target,
 377 we have the USB to I2C_Slave bridge we need: one TERMINAL for up to 112 I2C_FastForth targets.
 378
 379                                                                                       +-------------------------+
 380         notebook                     USB to I2C_Slave bridge                    +-I2C-| others I2C_slave target |
 381       +-----------+      +-------------------------------------------------+   /    +-------------------------+ |
 382       |           |      ¦ PL2303HXD         target running UARTI2CS @24MHz¦  +-I2C-|  MSP430FR4133 @ 1 MHz   | |
 383       |           |      ¦------------+       +----------------------------¦ /   +--------------------------+ |-+
 384       |           |      ¦            | 3wires|   MSP430FR2355 @ 24MHz     ¦/    |   MSP430FR5738 @ 24 MHz  | |
 385       | TERATERM -o->USB-o->USB2UART->o->UART-o-> FAST FORTH -> UARTI2CS  -o-I2C-o-> FAST FORTH with option |-+
 386       | terminal  |      ¦            | 6MBds |               (I2C MASTER) ¦     |  TERMINAL_I2C (I2C SLAVE)|
 387       |           |      ¦------------+       +----------------------------¦     +--------------------------+
 388       |           |      ¦            |< 20cm>|                            ¦       up to 112 I2C_Slave targets
 389       +-----------+      +-------------------------------------------------+
 390
 391 With the indicated MCLK and UART speed, Coretest.4th (45896 bytes) is downloaded to (and executed by) I2C_Slave in 1220ms.
 392 The driver UARTI2CS works without error from 1MHz to 24MHz MCLK and from 115200Bds up to 6MBds UART.
 393 With I2C_Master running at 24 MHz, the I2C bus frequency is about 1MHz, and it works fine
 394 even if I2C_slave is running at 1 MHz.
 395 Don't forget to add two 3k3 pullup resistors on SCL and SDA...
 396
 397 the Multi Master Mode works but is not tested in multi master environment.
 398
 399 "Cerise sur le gâteau": when they wait for a TERMINAL input (idle state),
 400 both I2C_Master and I2C_Slave(s) are sleeping in LPMx mode and the bus I2C is freed.
 401 The I2C_slave driver handles LPM4 mode.
 402
 403 The UART2I2CS does not use TI's horrible UCBx_I2C_Master driver, but a much faster software driver,
 404 with one more UCBx still available for an I2C_Slave or SPI driver.
 405
 406 ##### HOW TO DO ?
 407
 408     first you make the I2C cable (GND,SDA,SCL,3V3) between your 2 LaunchPad, with 3,3k pullup resistors
 409     on SDA and SCL lines. See in forthMSP430FR_TERM_I2C.asm to select SDA and SCL pins.
 410
 411     to compile FastForth for I2C TERMINAL from forthMSP430FR.asm file:
 412     -  uncomment the line "TERMINAL_I2C".
 413     -  search "I2CSLAVEADR" line and set your <slave address you want>, i.e. 10h.
 414     -  compile file then prog your I2C_Slave LaunchPad.
 415
 416     with the another LaunchPad running FastForth:
 417     At the end of UART2I2CS.f file set the <slave address you want>, i.e. $10.
 418     then download it, it's done: TERMINAL is linked to I2C_Slave.
 419
 420     Type `Alt+B` on teraterm (send a BREAK) or press S2 on UARTtoI2C module to unlink I2C_Slave.
 421
 422 ### PREVIOUS versions
 423
 424 Unlocking I/O's is transfered from RESET to WARM.
 425 Thus, by redefining HARD_APP, you can add I/O's configuration for your application before a global unlocking.
 426
 427
 428 The structure of primary DEFERred words as KEY,EMIT,CR,ACCEPT... is modified,
 429 the address of their default execute part, without name, can be found with: `' <name> >BODY`
 430
 431 example, after this entry: `' DROP IS KEY` KEY runs DROP i.e. runs the redirection made by IS,
 432
 433 but `' KEY >BODY EXECUTE` runs KEY, the default action at the BODY address.
 434
 435 and `' KEY >BODY IS KEY` restores the default action of this **primary** DEFERred word.
 436
 437
 438 to build a **primary** DEFERred definition, you must create a CODE definition followed by a :NONAME definition:
 439
 440     CODE SPACES         \ create a CODE definition named 'SPACES' which does a jump to the NEXT_ADR instruction to do nothing
 441     MOV #NEXT_ADR,PC    \ CFA = code of the instruction, PFA = parameter I of the instruction = NEXT_ADR
 442     ENDCODE             \ this definition 'SPACES' does nothing, for the moment...
 443
 444     :NONAME             \ starts a FORTH definition without name
 445     BEGIN
 446         ?DUP
 447     WHILE
 448         'SP' EMIT
 449         1-
 450     REPEAT
 451     ;
 452     IS SPACES           \ this :NONAME execution_address is stored at PFA of SPACES, replacing NEXT_ADR
 453
 454 The advantage of creating primary DEFERred definitionss is to set their
 455 default execution subroutine at their BODY address, enabling to reinitialize them easily:
 456 ' truc >BODY IS truc
 457
 458 Same with CODENNM definition, as low level equivalent of :NONAME
 459
 460     CODE TSTBIT         \ create a CODE definition named 'TSTBIT' which does a jump to the NEXT_ADR instruction to do nothing
 461     MOV #NEXT_ADR,PC    \ CFA = instruction, PFA = NEXT_ADR
 462     ENDCODE             \ this definition 'TSTBIT' does nothing, for the moment...
 463
 464     CODENNM             \ starts an assembly definition without name
 465     MOV @PSP+,X
 466     AND @X,TOS
 467     MOV @IP+,PC
 468     ENDCODE             \ -- execution_address_of_CODENNM
 469     IS TSTBIT           \ this CODENNM execution_address is stored at PFA of TSTBIT, replacing NEXT_ADR
 470
 471 you can obviously mix LOW/HIGH levels in CODENNM and :NONAME
 472
 473 All interpretation/compilation errors now execute ~~`PWR_RET`~~ `RST_RET`, so any incorrect definition
 474 and all its source file will be automatically erased.
 475
 476
 477 Accept SD_Card from 4 to 64 GB (FAT32).
 478 Note that Windows 10 no longer offers the FAT32 format for the highest sizes of SD_CARD memory.
 479 So you must use an alternative to do, for example: https://www.partitionwizard.com.
 480
 481
 482 Added direct file transfer from PC to the target SD_CARD.
 483 Measured throughput with "HCI" SD CARD: 90 kbytes/s at 3Mbauds TERMINAL and 16MHz MCLK.
 484 You can do it from scite editor (menu Tools) or by using specific bat file.
 485 Double click on it to see how to do.
 486
 487 JTAG and BSL signatures (FF80h-FF88h) are protected against overwrite during source file download.
 488
 489
 490 ## Many thanks to Brad Rodriguez
 491
 492 for his CamelForth which served me as a kind of canvas.
 493 And also to Matthias Koch for its ideas about Q15.16 implementation.
 494
 495 Unlike CamelForth FASTFORTH is a "Direct Threaded Code", with an embedded assembler following the standard syntax,
 496 not the one used in the world Forth.
 497
 498 It is 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.
 499 Everything can be done from your text editor, the preprocessor and a serial terminal.
 500
 501 ## What's this and why?
 502
 503 I have first programmed atmel tiny devices.
 504 Particularly I2C master driver to have both I2C slave and I2C master on a ATtiny461.
 505 which means a lot of back and forth between the editor, assembler, the programmer and the test in situ.
 506
 507 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.
 508
 509 The advent of chip MSP430 TEXAS INSTRUMENT with embedded FRAM gave me the idea to do it again : FAST FORTH was born.
 510
 511 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.
 512
 513 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.
 514
 515
 516 ## build your FastForth local copy
 517
 518 download https://framagit.org/Jean-Mi/FAST-FORTH/tree/master
 519 Once you have unzipped it into your folder, share it - with you - and notice its network path.
 520 Then right clic on the root of your notepad to create a network drive by recopying this network path (change backslashes \ to / ); then set drive letter as you want.
 521
 522 In explorer you should obtain this back your driver letter:
 523
 524
 525     \ForthMSP430FR.asm                main FASTFORTH program
 526     \ForthMSP430FR_ASM.asm            assembler
 527     \ForthMSP430FR_EXTD_ASM.asm       extended assembler
 528     \ForthMSP430FR_CONDCOMP.asm       conditionnal compilation
 529     \ForthMSP430FR_SD_ACCEPT.asm      ACCEPT for SD_Card
 530     \ForthMSP430FR_SD_INIT.asm        init SD_CARD (FAT16/32)
 531     \ForthMSP430FR_SD_LOAD.asm        load source files from SD_CARD
 532     \ForthMSP430FR_SD_LowLevel.asm    SPI routines + Read / write sector
 533     \ForthMSP430FR_SD_RW.asm          read create write del SD_CARD files + file copy to SD_CARD
 534     \ForthMSP430FR_TERM_I2C.asm       I2C terminal
 535     \ForthMSP430FR_TERM_UART.asm      full duplex UART terminal
 536     \ForthMSP430FR_TERM_UART_HALF.asm half duplex UART terminal
 537     \SciTEDirectories.properties      copy of \config\scite\AS_MSP430\SciTEDirectories.properties
 538
 539     \ADD-ON\                          FASTFORTH OPTIONAL KERNEL ADD-ON (not erasable version)
 540            \CORE_ANS.asm              set of complementary words to pass CORETEST.4TH
 541            \FIXPOINT.asm              adds HOLDS F+ F- F* F/ F#S F. S>F
 542            \SD_TOOLS.asm              adds some trivial words to display sectors content
 543            \UTILITY.asm               adds WORDS, DUMP, ? .S .RS
 544
 545     \binaries\files.txt              ready for drag'n drop to prog.bat
 546              \prog(.bat)             to do...
 547
 548     \config\
 549            \SciTEUser.properties                copy it in your home directory
 550            \SciTEDirectory.properties           copy it to your project root folder
 551            \asm.properties                      configuration for *.inc,*.asm, .pat files
 552            \forth.properties                    configuration for *.f,*.4th files
 553            \SendFile.ttl                        TERATERM macro file to send source file to FASTFORTH
 554            \SendToSD.ttl                        TERATERM macro file to send source file to embedded SD_CARD
 555            \build(.bat)                         called by scite to build target.txt program
 556            \BSL_prog(.bat)                      to flash target with target.txt file with BSL_Scripter
 557            \FET_prog(.bat)                      to flash target with target.txt file with MSP430Flasher
 558            \Select.bat                          called to select target, device and deviceID
 559            \CopyTo_SD_Card(.bat)                to copy a file in the target SD_Card
 560            \SendSource(.bat)                    to send file to FASTFORTH
 561            \Preprocess(.bat)                    to convert generic .f file to specific .4th file
 562            \CopySourceFileToTarget_SD_Card.bat  create a link in any user folder for drag'n drop use
 563            \SendSourceFileToTarget.bat          create a link in any user folder for drag'n drop use
 564            \PreprocessSourceFile.bat            create a link in any user folder for drag'n drop use
 565
 566     \inc\                         MACRO ASsembler files.inc, files.asm, GEMA preprocessor files.pat
 567         \TargetInit.asm           select target configuration file for AS assembler
 568         \MSP_EXP430FRxxxx.asm     target minimalist hardware config to compile FastForth
 569         \ThingsInFirst.inc        general configuration for AS assembler
 570         \MSP430FRxxxx.inc         device declarations
 571         \ThingsInLast.inc         general post configuration for AS assembler
 572
 573         \FastForthREGtoTI.pat     converts FORTH symbolic registers names to TI Rx registers
 574         \tiREGtoFastForth.pat     converts TI Rx registers to FORTH symbolic registers names
 575         \MSP430FRxxxx.pat         FastForth generic declarations for INFO TLV FRAM areas
 576         \MSP430FR2xxx.pat         FastForth RAM declarations for FR2xxx and FR4xxx families
 577         \MSP430FR57xx.pat         FastForth RAM declarations for FR57xx family
 578         \MSP430FR5xxx.pat         FastForth RAM declarations for FR5xxx and FR6xxx families
 579         \MSP_EXP430FRxxxx.pat     target (launchpad) configuration
 580
 581     \prog\        SciTEGlobal.properties, TERATERM.INI + programs.url
 582
 583 ### FORTH generic_source_files.f and targeted_source_files.4th
 584
 585     \MSP430-FORTH\
 586                  \PreprocessSourceFile.bat            (link)
 587                  \SendSourceFileToTarget.bat          (link)
 588                  \CopySourceFileToTarget_SD_Card.bat  (link)
 589                  \*.f            source files which must be preprocessed before downloading
 590                  \*.4th          source files ready to download to any target
 591                  \LAST.4TH       last source target file issued by preprocessor
 592                  \BOOT.f         performs bootstrap
 593                  \CHNGBAUD.f     allows you to change terminal baudrate
 594                  \CORE_ANS.f     same as CORE_ANS.asm, (but erasable)
 595                  \CORETEST.4TH   ANS core tests
 596                  \CORDIC.f       for afficionados
 597                  \DOUBLE.f       adds DOUBLE word set
 598                  \FIXPOINT.f     same as FIXPOINT.asm, (but erasable)
 599                  \FF_SPECS.f     shows all specificities of FAST-FORTH compiled on your target
 600                  \RTC.f          set date and time, one example of MARKER use.
 601                  \RC5toLCD.f     multitasking example
 602                  \SD_TEST.f      tests for SD_CARD driver
 603                  \SD_TOOLS.f     same as SD_TOOLS.asm, (but erasable)
 604                  \TESTASM.f      some tests for embedded assembler
 605                  \TESTXASM.f     some tests for embedded extended assembler
 606                  \UARTI2CS.f     I2C_Master driver to link TERMINAL UART with any I2CSlave target
 607                  \UTILITY.f      same as UTILITY.asm, (but erasable)
 608
 609
 610 Note: all actions (flashing target, download files) can be made by using bat files directly.
 611 The next is to download IDE (WINDOWS):
 612
 613 ## First get TI's programs
 614
 615 [MSP430-FLASHER](https://www.ti.com/tool/MSP430-FLASHER), [MSP430_FET_Drivers](http://software-dl.ti.com/msp430/msp430_public_sw/mcu/msp430/MSP430_FET_Drivers/latest/index_FDS.html)
 616
 617 install in the suggested directory, then copy MSP430Flasher.exe and MSP430.dll to \prog\
 618
 619 ## download IDE
 620
 621 * [modified BSL-Scripter.zip](https://github.com/drcrane/bslscripter-vs2017/releases) and unzip as \prog\BSL-Scriper.exe
 622
 623 * [teraterm](https://osdn.net/projects/ttssh2/releases/)
 624
 625 * [GEMA general purpose preprocessor](https://sourceforge.net/projects/gema/files/latest/download), unzip in drive:\prog\
 626
 627 * [sCiTE single file executable](https://www.scintilla.org/SciTEDownload.html) to drive:\prog\, then rename Scxxx.exe to scite.exe
 628
 629 * [Macro AS](http://john.ccac.rwth-aachen.de:8000/ftp/as/precompiled/i386-unknown-win32/aswcurr-142-bld158.zip), unzip in drive:\prog\
 630
 631 * [srecord](https://sourceforge.net/projects/srecord/files/srecord-win32/1.64/), unzip in drive:\prog\
 632
 633
 634 In explorer you should obtain that (minimum requested programs):
 635
 636
 637     \prog\as.msg
 638          \asw.exe
 639          \BSL-Scripter.exe
 640          \cmdarg.msg
 641          \gema.exe
 642          \ioerrs.msg
 643          \MSP430.dll
 644          \MSP430Flasher.exe
 645          \P2hex.exe
 646          \P2hex.msg
 647          \srec_cat.exe
 648          \sCiTE.exe
 649          \SciTEGlobal.properties
 650          \tools.msg
 651
 652
 653 Next we need to change the drive letter in hard links below:
 654
 655     \binaries\prog.bat
 656     \MSP430-FORTH\SendSourceFileToTarget.bat
 657                  \CopySourceFileToTarget_SD_Card.bat
 658                  \PreprocessSourceFile.bat
 659
 660 to do, right clic on them
 661      select "properties"
 662             set your drive letter in "target"
 663
 664 The last step is ask Windows to associate scite editor with file types:
 665
 666 right clic on a .asm file,
 667     select "open with",
 668             select "other application" then select: drive:\prog\scite.exe
 669
 670 repeat for .inc, .lst, .f, .4th, .pat, .properties, .TTL files.
 671
 672
 673 IT's done ! See  forthMSP430FRxxxx.asm to configure TeraTerm
 674
 675
 676 ## Build the program file
 677
 678 \forthMSP430FR.asm is the main file to compile FastForth:
 679
 680 * Open forthMSP430FR.asm with scite editor
 681
 682 * uncomment the target as you want, i.e. MSP_EXP430FR5969
 683
 684 * choose frequency, baudrate, flow control.
 685
 686 * comment / uncomment options switches as your convenience.
 687
 688 * save file.
 689
 690 * assemble (CTRL+0). A window asks you for 4 parameters:
 691
 692 * set your target as first param, i.e. MSP_EXP430FR5969
 693
 694 * then execute. the output will be \binaries\MSP_EXP430FR5969.txt
 695
 696 ## Load Txt file (TI format) to target
 697
 698     in \binaries folder, drag your target.txt file and drop it on prog.bat
 699
 700     or use scite internal command TOOLS: FET prog (CTRL+1).
 701
 702 nota : programming the device use SBW2 interface, so UARTn is free for serial terminal connexion.
 703
 704 If you want to program your own MSP430FRxxxx board, wire its pins TST, RST, 3V3 and GND
 705 to same pins of the launchpad, on eZ-FET side of the programming connector.
 706
 707 ## Connect the FAST FORTH target to a serial terminal
 708
 709 you will need an USBtoUART cable with a PL2303TA|PL2303HXD|PL1303GC device that allows both XON/XOFF
 710 and hardware control flow :
 711
 712 [PL2303GC](https://duckduckgo.com/?q=DSD+TECH+SH-U06A+PL2303GC)
 713 [PL2303 driver](http://www.prolific.com.tw/US/ShowProduct.aspx?p_id=225&pcid=41)
 714
 715 WARNING! always verify VCC PIN = 3.3V before use to supply your target with.
 716
 717 or with a CP2102 device and 3.3V/5V that allows XON/XOFF control flow up to 921600 Bds:
 718
 719 [CP2102 3.3V](https://duckduckgo.com/q=cp2102+3.3V+6PIN)
 720 [CP2102 driver](https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers)
 721
 722 WARNING! always verify VCC PIN = 3.3V before use to supply your target with.
 723
 724
 725 ## Send a source file.f or file.4th to the FAST FORH target
 726
 727 Three bat files are done in \MSP430-FORTH that enable you to do all you want.
 728 drag and drop your source file on to.
 729 you can also open any source file with scite editor, and do all you want via its Tools menu.
 730
 731 If you have any downloading error, first verify in "LAST.4th" that all lines are
 732 correctly ended with CR+LF.
 733
 734 ## SD_Card driver
 735
 736 #### First, hardware
 737
 738 If you have MSP-EXP430FR5994, nothing to do.
 739
 740 For the choice of a SD card socket be carefull, pin CD (Card Detect) must be present!
 741 Look for the good wiring in /Launchpad.asm file
 742
 743 #### Compile with SD_Card addon
 744
 745 in forthMSP430FR.asm, uncomment lines SD_CARD_LOADER,  SD_CARD_READ_WRITE
 746 then compile for your target
 747
 748 ### the commands
 749
 750 With the `LOAD"` pathame" command FastForth loads source files from a SD_CARD memory.
 751
 752     * LOAD" path\filename.4th" relative path,
 753
 754     * LOAD" \path\filename.4th" absolute path.
 755
 756 The file is interpreted by FORTH in same manner than from the serial terminal.
 757 When EOF is reached, the file is automatically closed.
 758 A source file can `LOAD"` another source file, and so on in the limit of 8 handles.
 759
 760 `LOAD"` may be used as Change Directory command:
 761
 762     * LOAD" \misc".       \misc becomes the current folder.
 763
 764     * LOAD" ..\"          parent folder becomes the current folder.
 765
 766     * LOAD" \"            Root becomes the current folder.
 767
 768
 769 To read a file: `READ"` pathname"
 770
 771 * open it, the first sector is loaded in SD_BUF
 772
 773 The command `READ` sequentially loads the next sector in the buffer and leaves on the stack a true flag when the EOF is reached.
 774 The variable BufferLen keep the count of bytes to be read (1 to 512).
 775
 776 The file is automatically closed.
 777
 778 If you want to anticipate the end, remove the false flag left by the previous `READ` then use the `CLOSE` command.
 779
 780 To overwrite a file: `WRITE"` path\filename.ext".
 781
 782 * If the file does not exist, create it
 783
 784 * set the write pointer at the **beginning** of the file, ready to append chars.
 785
 786 To write a file: `APPEND"` path\filename.ext".
 787
 788 * If the file does not exist, create it
 789
 790 * set the write pointer at the **end** of the file, ready to append chars.
 791
 792 The command `WRITE` sequentially writes the SD_BUF in SD_CARD and increments the current sector.
 793
 794 Use `CLOSE` to close a WRITE file.
 795
 796 See examples of use in \MSP430-FORTH\SD_TEST.f.
 797
 798
 799 #### Copy source file to SD_Card
 800
 801 to copy a source file (.f or.4th) to SD_CARD target, use CopySourceFileToTarget\_SD\_Card.bat.
 802 Double click on one of this bat files to see how to do.
 803
 804 or use scite.
 805
 806 If you have any copy error, first verify in "LAST.4th" that all lines are
 807 correctly ended with CR+LF.
 808
 809 ## The system is not responding ?
 810
 811 First, remove the USBtoUART bridge then reconnect it. Perhaps it was in suspend state...
 812
 813 If the system is always freezed, press `RST` button on the MSP-EXP430FR5xxx ; FORTH restarts
 814 as it was after the last `RST_SET` command.
 815
 816 If the system does not restart again, press `SW1+RESET`.
 817 FORTH restarts in the state of its object file.
 818
 819 Here is the FastForth memory management, one of its major assets, with both hardware events and software equivalent:
 820
 821 *  RST_RET
 822
 823     *  when you type `RST_RET` the program beyond the last RST_SET is lost.
 824
 825     *  Running a `MARKER` definition will remove it and the program beyond. In addition the user can link it a routine to remove the modified configuration in system: vectors, hardware, I/Os...
 826
 827
 828 *  WARM level : `SYS` -->(no PUC)--> INIT_FORTH --> INIT_HARD --> WARM display --> ABORT --> ACCEPT --> BACKGRND --> SLEEP.
 829
 830     *  when you type `SYS`, FORTH restarts, the WARM display starts by #0.
 831
 832     *  when you type `+n SYS` (n>0, odd), the WARM display starts by #+n.
 833
 834         * same effect as RST_RET
 835
 836         * words ACCEPT, EMIT, KEY are initialised with their default value,
 837
 838         * TIB is initialised with its default value.
 839
 840
 841 *  COLD level : `+n SYS` --> PUC --> INIT_FORTH --> INIT_HARD --> WARM display --> ABORT --> ACCEPT --> BACKGRND --> SLEEP.
 842
 843     *  Power ON : the WARM display starts with the SYSRSTIV value #2.
 844
 845     *  hardware `RST` : the WARM display starts with the SYSRSTIV value #6, because RST pin acts as NMI pin.
 846
 847     *  SVSHIFG SVSH event (supply dropout) : the WARM display starts with the SYSRSTIV value: #14.
 848
 849     *  PUC on failure : the WARM display starts with the SYSRSTIV value: #n.
 850
 851     *  other `+n SYS` (n>0 and even) are software RESET : the WARM display starts with the SYSRSTIV value "#+n" (even).
 852
 853         * same effects as WARM level, plus:
 854
 855         * performs a PUC.
 856
 857
 858
 859 *  DEEP RESET level:
 860
 861     *  `-n SYS` (n<0) performs the software Deep Reset, WARM display = #-n.
 862
 863     *  hardware `SW1+RESET`, WARM display = #-1.
 864
 865     *  recompiling FastForth, WARM display = #-3.
 866
 867         * same effects as COLD level, plus:
 868
 869         *  all programs donwloaded from the TERMINAL or from the SD_CARD are lost,
 870
 871         *  COLD_APP, ABORT_APP, SOFT_APP, HARD_APP and BACKGND_APP default values are restored,
 872
 873         *  all interrupts vectors are initialised with their default value,
 874
 875         *  SIGNATURES area is FFh full filled.
 876
 877
 878 * ERROR : ABORT" your_text" --> INIT_FORTH --> display = "your_text" --> ABORT --> ACCEPT --> BACKGRND --> SLEEP.
 879
 880     *  when an error occurs, FASTFORTH discards the end of current downloading if any. In this way, any error is followed by the complete erasure of the bad defined word causing this error, and also by discarding the end of downloading of the source file including it.
 881
 882
 883 Once validate, it is strongly recommended to end any source file with `RST_SET` to protect the resulting program from a subsequent download error.
 884
 885 As all other FORTH words, `RST_SET` `RST_RET` and` MARKER` definitions may be freely used in compiling mode.
 886
 887 If you have previously set `NOECHO`, there is no WARM display.
 888
 889 If you don't want to display an ABORT" message, type: `ABORT" "`
 890
 891 With I2C_FastForth version, WARM and `ABORT"` displays are preceded by the decimal I2C slave address, example: `@18`.
 892
 893
 894 ## VOCABULARY ADD-ON
 895
 896 These words are not ANS94 compliant.
 897
 898 The CONTEXT stack is 8 word_set sized.
 899
 900 after typing: `WORDSET TRUC`   a new word-set called TRUC is created, then:
 901
 902 * `TRUC`            adds the word-set TRUC first in the CONTEXT stack, the interpreter search existing definitions first in TRUC
 903
 904 * `DEFINITIONS`     adds news definitions in the first word-set in the CONTEXT stack, i.e. TRUC,
 905 * `PREVIOUS`        removes TRUC from CONTEXT but new definitions are still added in TRUC
 906 * `DEFINITIONS`     new definitions are added into the previous first word-set in the CONTEXT stack,
 907 *  after `-1 SYS`, FORTH is the CONTEXT and the CURRENT word-set.
 908
 909
 910 ## EMBEDDED ASSEMBLER
 911
 912 The preprocessor GEMA allows the embedded assembler to access all system variables.
 913 See files \\inc\\Target.pat.
 914
 915 ### HOW TO MIX assembly and FORTH ?
 916
 917 FAST FORTH knows two modes of definitions :
 918
 919 * high level FORTH definitions `: <name> ... ;`
 920
 921 * assembly low level definitions `CODE <name> ... ENDCODE`
 922
 923 there is also some variations of these two modes :
 924
 925 * high level definitions `NONAME: ... ;`
 926
 927 * low level definitions `CODENNM ... ENDCODE`, low-level equivalent of `NONAME:`
 928
 929 * low level definitions `HDNCODE <name> ... ENDCODE`, these definitions are 'hidden' and can be accessed only from assembly level.
 930
 931 Examples:
 932
 933     : NOOP              \ FORTH definition "NOOP", does nothing
 934         DUP
 935         DROP
 936     ;
 937
 938
 939     CODE ADD            \ low level definition "ADD", alias of word +
 940         ADD @PSP+,TOS
 941         MOV @IP+,PC
 942     ENDCODE
 943
 944
 945     HDNCODE WDT_INT         \ low level hidden definition "WDT_INT" (Watchdog interrupt)
 946     BIT #8,&TERM_STATW      \ break (ALT+b) sent by TERMINAL ?
 947     0<> IF                  \ if yes
 948         MOV #ABORT,PC       \   continue with ABORT (no return)
 949     THEN
 950                             \ else return to background task SLEEP
 951     BIC #%0111_1000,0(RSP)  \ force CPU Active Mode, disable all interrupts
 952     RETI                    \
 953     ENDCODE
 954
 955
 956 At the end of low level CODE definition, the instruction MOV @IP+,PC jumps to the next definition.
 957 This faster (4 cycles) and shorter (one word) instruction replaces the famous pair of assembly
 958 instructions : CALL #LABEL ... RET (4+4 cycles, 2+1 words).
 959 The register IP is the Interpretative Pointer.
 960
 961 High level FORTH definitions starts with a boot code "DOCOL" which saves the IP pointer and loads it with the first address
 962 of a list of execution addresses, then performs a postincrement branch to the first one.
 963 The list ends with the address of another piece of code: EXIT (6 cycles) which restores IP from stack before the instruction MOV @IP+,PC.
 964
 965 here, the compilation of low level ADD definition :
 966
 967                     header          \ compiled by the word CODE
 968     execution addr  ADD @PSP+,TOS
 969                     MOV @IP+,PC     \ instruction called NEXT
 970
 971 and the one of the high level word NOOP :
 972
 973                     header          \ compiled by the word :
 974     execution addr  PUSH IP         \ boot code "DOCOL"...
 975                     CALL rDOCOL     \ ...compiled by the word :
 976                     addr of DUP     \ execution addr of DUP
 977                     addr of DROP    \ execution addr of DROP
 978                     addr of EXIT    \ execution addr of EXIT compiled by the word ;
 979
 980 _A high level FORTH word is a list of execution addresses preceded by a boot code and ending with EXIT address._
 981
 982 ### WRITING RULES
 983
 984 any low level FORTH words must be ended with the instruction MOV @IP+,PC (NEXT).
 985
 986         CODE TEST               \ CODE starts a low level word
 987             asm1                \ assembly instruction 1
 988             asm2                \ assembly instruction 2
 989             MOV @IP+,PC         \ NEXT
 990         ENDCODE                 \ end of low level word
 991
 992 If you want to use the IP register, save it before and restore it before NEXT
 993
 994         CODE TEST1              \ CODE starts a low level word
 995             asm1                \ assembly instruction
 996             ...
 997             PUSH IP             \ save IP before use
 998             MOV #1,IP           \ assembly instruction that uses IP
 999             ...                 \ assembly instructions
1000             MOV @RSP+,IP        \ restore IP
1001             MOV @IP+,PC         \ NEXT
1002         ENDCODE                 \ end of low level word
1003
1004 A little more complex, the case of mixing FORTH and assembly with use of the words HI2LO, LO2HI and COLON
1005
1006         : MIX_FORTH_ASM         \ definition of a FORTH word starts with :
1007             SWAP
1008             DUP
1009         HI2LO                   \ FORTH to assembler switch
1010             asm1                \ you can freely use IP
1011             asm2
1012             ...
1013             ...
1014             MOV @RSP+,IP        \ restore IP stacked by :
1015             MOV @IP+,PC         \ goto NEXT
1016         ENDCODE                 \ end of low level word, compile nothing
1017
1018 If we see the code "MIX\_FORTH\_ASM" after compilation :
1019
1020             header              \ compiled by :
1021     exec@   PUSH IP             \
1022             CALL rDOCOL
1023             addr of SWAP
1024             addr of DUP
1025             next addr           \ addr of asm1, compiled by HI2LO
1026             asm1
1027             asm2
1028             ...
1029             ...
1030             MOV @RSP+,IP        \ restore IP saved by boot code
1031             MOV @IP+,PC         \ NEXT
1032
1033 going a step further :
1034
1035         CODE MIX_ASM_FORTH      \ CODE starts a low level word
1036             asm1
1037             asm2
1038         COLON                   \ starts high level
1039             word1
1040             word2
1041         ;                       \ end of high level word, compile EXIT
1042
1043 If we see this code "MIX\_ASM\_FORTH" after compilation :
1044
1045             header              \ compiled by CODE
1046     exec@   asm1
1047             asm2
1048     DOCOL   PUSH IP
1049             CALL rDOCOL         \ "DOCOL" compiled by COLON
1050             addr of word1
1051             addr of word2
1052             addr of EXIT        \ EXIT restores IP from stack then executes MOV @IP+,PC
1053
1054 A new step:
1055
1056         : MIX_FORTH_ASM_FORTH   \ definition of a FORTH word starts with :
1057             word1
1058             word2
1059             ...
1060         HI2LO                   \ FORTH to assembler switch
1061             MOV #0,IP           \ IP is free for use
1062             asm1
1063             ...
1064         LO2HI                   \ assembler to FORTH switch
1065             word3
1066             word4
1067         ;                       \ end of high level word
1068
1069 the compiled result
1070
1071             header              \ )
1072     exec@   PUSH IP             \ > compiled by :
1073             CALL rDOCOL         \ )
1074             addr of word1
1075             addr of word2
1076             ...
1077             next addr           \ compiled by HI2LO
1078             MOV #0,IP           \ IP is free for use
1079             asm1                \ assembly instruction
1080             ...
1081             CALL rDOCOL         \ compiled by LO2HI
1082             addr of word3
1083             addr of word4
1084             addr of EXIT        \ compiled by ;
1085
1086 Still another step :
1087
1088         CODE MIX_ASM_FORTH_ASM  \ CODE starts a low level word
1089             asm1
1090             asm2
1091         COLON                   \ start high level definition
1092             word
1093             ...
1094         HI2LO                   \ switch high to low level
1095             asm3
1096             asm4
1097             MOV @RSP+,IP        \ restore IP
1098             MOV @IP+,PC         \ goto NEXT
1099         ENDCODE                 \ end of low level word
1100
1101 In fact, an exclusive of FAST FORTH, the start of a word FORTH can be placed anywhere :
1102
1103         CODE MIX_ASM_FORTH_ASM_FORTH
1104             asm1
1105             asm2
1106             ...
1107         COLON                   \ starts high level definition
1108             word1
1109             word2
1110             ...
1111         HI2LO                   \ FORTH to assembler switch
1112             asm3
1113             asm4
1114            ...
1115         LO2HI                   \ assembler to FORTH switch
1116             word
1117             word
1118             ...
1119         ;                       \ end of high level word
1120
1121 with the compiled result :
1122
1123             header              \ compiled by CODE
1124     exec@   asm
1125             asm
1126     DOCOL   PUSH IP             \ compiled...
1127             CALL rDOCOL         \ ...by COLON
1128             addr
1129             addr
1130             next address        \ compiled by HI2LO
1131             asm
1132             asm
1133             CALL rDOCOL         \ compiled by LO2HI
1134             addr
1135             addr
1136             EXIT addr           \ that restores IP from return stack and then executes MOV @IP+,PC
1137
1138
1139 ### ASSEMBLER WITHOUT LABELS ? YES !
1140
1141 To compare AS macro assembler and FastForth embedded assembler,
1142 compare files \ADDON\FIXPOINT.asm and \MSP430-FORTH\FIXPOINT.f
1143
1144 The conditionnal instructions doesn't use labels.
1145 Instead, they borrow FORTH's conditional environment:
1146
1147     CODE TEST_IF_THEN
1148         CMP #1,R8           \ set Z,N,V, flags
1149         0= IF               \ irritating, the "IF 0=" upside down, isn't it?
1150             ADD R8,R9       \ true part of comparaison
1151         THEN
1152         ...                 \ the next
1153         ...
1154         MOV @IP+,PC         \ don't forget...
1155     ENDCODE                 \ don't forget...
1156
1157 and the complete version :
1158
1159     CODE TEST_IF_ELSE_THEN
1160         CMP #1,R8           \ set Z,N,V, flags
1161         0= IF               \
1162             ADD R8,R9       \ true part of comparaison
1163         ELSE
1164             SUB R8,R9       \ false part of comparaison
1165         THEN
1166         ...                 \ the next for the two branches
1167         MOV @IP+,PC
1168     ENDCODE
1169
1170 test for loop back version BEGIN ... UNTIL
1171
1172     CODE TEST_BEGIN_UNTIL
1173         MOV #8,R10
1174         BEGIN
1175             SUB #1,R10      \ set Z,N,V flags
1176         0= UNTIL            \ loop back to BEGIN if flag Z is not set
1177         ...
1178         MOV @IP+,PC
1179     ENDCODE
1180
1181 test for out of loop version BEGIN ... WHILE ... REPEAT
1182
1183     CODE TEST_BEGIN_WHILE_REPEAT
1184         MOV #8,R10
1185         BEGIN
1186             SUB #1,R10      \ set Z,N,V flags
1187         0<> WHILE           \ go to out of loop if X=0 (Z flag =1)
1188             XOR #1,R9
1189         REPEAT              \ unconditionnal loop back to BEGIN
1190         ...                 \ out of loop here
1191         MOV @IP+,PC
1192     ENDCODE
1193
1194 infinite loop :
1195
1196     CODE TEST_BEGIN_AGAIN
1197         BEGIN
1198             ADD #1,R9
1199         AGAIN               \ unconditionnal loop back to BEGIN
1200     ENDCODE
1201
1202 to quit this infinite loop, press reset.
1203
1204 We can nest several conditional branches :
1205
1206     CODE TEST_NESTED_IF_ELSE
1207         CMP #0,R10
1208         0= IF
1209             CMP #0,R10
1210             0= IF
1211                 MOV #0,R11
1212             ELSE
1213                 SUB #1,R11
1214             THEN
1215         ELSE
1216             MOV #1,R11
1217         THEN
1218         MOV @IP+,PC
1219     ENDCODE
1220
1221 another nest :
1222
1223     CODE TEST_NESTED_BEGIN_AGAIN_IF
1224         MOV #8,R9
1225         BEGIN
1226             CMP #-1,R9
1227             0= IF
1228                 MOV @IP+,PC \ out of test_NESTED_BEGIN_AGAIN_IF
1229             THEN
1230             SUB #1,R9
1231         AGAIN
1232     ENDCODE
1233
1234 you can MIX conditional branches with a mix of FORTH/assembly: see TEST5 in the demo file \MSP430-FORTH\TESTASM.4TH
1235
1236
1237 FAST FORTH have one pass assembler, not able to resolve forward jumps.
1238
1239 I have added possibility of several "non canonical" jumps, up to 3 backward and up to 3 forward jumps to label :
1240
1241     \ C UM/MOD   udlo|udhi u1 -- ur uq
1242     CODE UM/MOD
1243         MOV @PSP+,W     \ 2 W = DIVIDENDhi
1244         MOV @PSP,S      \ 2 S = DIVIDENDlo
1245     \ T.I. ROUTINE  Section 5.1.5 of MSP430 Family Application Reports
1246         MOV #0,Y        \ 1 CLEAR RESULT
1247         MOV #16,X       \ 2 INITIALIZE LOOP COUNTER
1248     BW1 CMP TOS,W       \ 1
1249         U>= IF          \ 2
1250             SUB TOS,W   \ 1 if carry DIVIDENDhi-divisor
1251         THEN
1252     BEGIN
1253         ADDC Y,Y        \ 1 RLC quotient
1254         U>= ?GOTO FW1   \ 2 if carry Error: result > 16 bits
1255         SUB #1,X        \ 1 Decrement loop counter
1256         <0 ?GOTO FW2    \ 2 if 0< terminate w/o error
1257         ADD S,S         \ 1 RLA DIVIDENDlo
1258         ADDC W,W        \ 1 RLC DIVIDENDhi
1259         U< ?GOTO BW1    \ 2 if not carry    14~ loop
1260         SUB TOS,W       \ 1 if carry DIVIDENDhi-divisor
1261         BIS #1,SR       \ 1 SETC
1262     AGAIN               \ 2                 14~ loop
1263     FW2 BIC #1,SR       \ 1 CLRC  No error, C = 0
1264     FW1                 \  Error indication in C
1265     \ END of T.I. ROUTINE  Section 5.1.5 of MSP430 Family Application Reports
1266         MOV W,0(PSP)    \ 3 remainder on stack
1267         MOV Y,TOS       \ 1 quotient in TOS
1268         MOV @IP+,PC     \ 4
1269     ENDCODE
1270
1271 Forward labels FWx are for single use, backward labels BWx can solve several jumps,
1272 until their new definition.
1273
1274 ### SYMBOLIC ASSEMBLER ? YES !
1275
1276 I have discovered a little semantic preprocessor "GEMA", just like that FAST FORTH have its symbolic assembler !
1277
1278 * \inc\DEVICE.pat contains memory map and vectors for a specified DEVICE
1279 * \inc\LAUNCHPAD.pat is the I/O config file for specific LAUNCHPAD (or application)
1280
1281 Gema translates FORTH registers in ASM registers (R0 to R15) via \inc\ThingsInFirst.pat
1282
1283 With the three bat files in \MSP430_FORTH folder all is done automatically.
1284
1285 ### WHAT ABOUT VARIABLES, CONSTANTS...
1286
1287 In addition to the FORTH VARIABLE and CONSTANT definitions, the macroassembler allows to use symbolic variables and constants
1288 which are compiled / executed as number by the FORTH interpreter, also by the assembler, but only in the scope of a source use.f file with their declaration done in a use.pat file.
1289
1290 On the other hand, the CONSTANT, VARIABLE and MARKER definitions are correctly handled by the assembler which provides for each case the expected argument: the constant, the address of the variable and the address of the first user variable with MARKER.
1291
1292 Example:
1293
1294     VARIABLE BASE
1295     $10 BASE !
1296     2 CONSTANT TWO
1297     MARKER {MYAPP}
1298     'ESC' , 'XON' C, 'XOFF' C,
1299
1300     HDNCODE EXAMPLE         \ hidden definition to be linked in the hidden word-set
1301     CMP #RET_ADR,&{MYAPP}-2 \ compare content of {MYAPP}-2 address with RET_ADR
1302     MOV &BASE,X             \ X = 16
1303     MOV #BASE,X             \ X = address of base
1304     MOV @X,X                \ X = 16
1305     MOV #TWO,Y              \ Y = 2
1306     MOV &{MYAPP},W          \ W = $1B
1307     MOV.B &{MYAPP}+2,W      \ W = 17
1308     MOV.B &{MYAPP}+3,W      \ W = 19
1309     MOV @IP+PC
1310     ENDCODE
1311
1312     CODE RUN_EXAMPLE
1313     MOV #EXAMPLE,PC         \ = BR EXAMPLE      runs EXAMPLE, without return
1314     ENDCODE
1315
1316
1317 # COMPILE FAST FORTH FOR YOUR TARGET
1318
1319 1- in forthMSP430FR.asm "TARGET configuration"  create a line for your target, example:
1320
1321     ;MY_MSP430FR5738_1 ; compile for my own MSP430FR5738 miniboard V1
1322
1323 2- create your \inc\MSP430FR5738_1.asm and \inc\MSP430FR5738.inc from another target.asm and device.inc as pattern,
1324 Notice that you must define here only the necessary for FAST-FORTH compilation.
1325
1326 3- in \inc\ThingsInFirst.inc add one "device.inc" item:
1327
1328         .IFDEF MY_MSP430FR5738_1
1329     UCA0_UART   ; defines uart used for TERMINAL
1330     LF_XTAL     ; defines if your module have a 32768 Hz xtal, to enable it.
1331     UCB0_SD     ; defines UC used for SD Card driver if any
1332         .include "MSP430FR5738.inc"  ; include device declarations
1333         .ENDIF
1334
1335 4- in \inc\TargetInit.asm add one "target.asm" item:
1336
1337         .IFDEF MY_MSP430FR5738_1
1338             .include MY_MSP430FR5738_1.asm
1339         .ENDIF
1340
1341 Then, for the preprocessor which you will use when downloading FORTH source files:
1342
1343 1- create your \inc\device.pat file if not exist, from your \inc\device.inc and/or another \inc\device.pat as pattern.
1344
1345 2- create your \inc\target.pat file from your \inc\target.asm and/or another \inc\target.pat as pattern.
1346
1347 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
1348 that is the reset state of FastForth...
1349
1350
1351 # ANNEXES
1352
1353 Here you have a good overview of MSP430 assembly:
1354 [MSP430 ISA](http://www.ece.utep.edu/courses/web3376/Notes_files/ee3376-isa.pdf)
1355
1356 FastForth embedded assembler doesn't recognize the (useless) TI's symbolic addressing mode: ADD.B EDE,TONI.
1357
1358 REGISTERS correspondence (you can freely use ASM or TI or FASTFORTH registers's names).
1359
1360         REG         TI      FASTFORTH   comment
1361
1362         R0          PC      PC          Program Counter
1363         R1          SP      RSP         Return Stack Pointer
1364         R2          SR/CG1              Status Register/Constant Generator 1
1365         R3          CG2                 Constant Generator 2
1366         R4          R4      R (rDOCOL)  contents address of xDOCOL (DTC=1|2)
1367         R5          R5      Q (rDODOES) contents address of xdodoes
1368         R6          R6      P (rDOCON)  contents address of xdocon
1369         R7          R7      M (rDOVAR)  contents address of RFROM
1370         R8          R8      Y           scratch register
1371         R9          R9      X           scratch register
1372         R10         R10     W           scratch register
1373         R11         R11     T           scratch register
1374         R12         R12     S           scratch register
1375         R13         R13     IP          Interpretation Pointer
1376         R14         R14     TOS         Top Of parameters Stack
1377         R15         R15     PSP         Parameters Stack Pointer
1378
1379 **REGISTERS use**
1380
1381 The FASTFORTH registers rDOCOL, rDOVAR, rDOCON and rDODOES must be preserved.
1382 If you use them you may either `PUSHM #4,M` before and `POPM #4,M after`,
1383 or use them directly then restore FastForth default values:
1384
1385 `MOV #INIT_DOXXX,X`
1386 `MOV @X+,rDOCOL`
1387 `MOV @X+,rDODOES`
1388 `MOV @X+,rDOCON`
1389 `MOV @X,rDOVAR`
1390
1391 (Search `INIT_DOXXX` in \inc\MSP430xxxx.pat)
1392
1393 If you want to restore only rDODOES, rDOCON and rDOVAR:
1394
1395 `MOV #INIT_DOXXX+2,X`
1396 `MOV @X+,rDODOES`
1397 `MOV @X+,rDOCON`
1398 `MOV @X,rDOVAR`
1399
1400 If you want to restore only rDODOES and rDOCON:
1401
1402 `MOV #XDODOES,rDODOES`
1403 `MOV #XDOCON,rDOCON`
1404
1405 When you use these registers you can't call any FORTH words using them at the same time!
1406
1407 don't use R3 and use R2 (SR) only with BIC, BIT, BIS instructions in register mode.
1408
1409 The bits 0-11 of SR register are saved by interrupts and restored by the instruction RETI.
1410 you can use freely UF9 UF10 and UF11 as SR bits 9-11.
1411 FastForth uses UF9 for double numbers interpreting and also by TO ... VALUE.
1412
1413
1414 **PARAMETERS STACK**
1415
1416 The register TOS (Top Of Stack) is the first cell of the Parameters stack.
1417 The register PSP (Parameters Stack Pointer) points the second cell.
1418
1419 to push one cell on the PSP stack :
1420
1421     SUB #2,PSP                  \ insert a empty 2th cell
1422     MOV TOS,0(PSP)              \ fill this 2th cell with first cell
1423     MOV(.B) <what you want>,TOS \ i.e. update first cell
1424
1425 to pop one cell from the PSP stack :
1426
1427     MOV @PSP+,TOS               \ first cell TOS is lost and replaced by the 2th.
1428
1429 don't never pop a byte with instruction MOV.B @PSP+, because it generates a stack misalignement...
1430
1431 **RETURN STACK**
1432
1433 register RSP is the Return Stack Pointer (SP).
1434
1435 to push one cell on the RSP stack: `PUSH <what you want>`
1436
1437 to pop one cell from the RSP stack: `MOV @RSP+,<where you want>`
1438
1439 don't never push or pop a byte on RSP stack !
1440
1441
1442 to push multiple registers on the RSP stack :
1443
1444 `PUSHM #n,Rx`,  with 0 <= x-(n-1) < 16
1445
1446 to pop multiple registers from the RSP stack :
1447
1448 `POPM #n,Rx`,  with 0 <= x-(n-1) < 16
1449
1450     PUSHM order : PSP,TOS, IP, S , T , W , X , Y ,rDOVAR,rDOCON,rDODOES,rDOCOL, R3, SR,RSP, PC
1451     PUSHM order : R15,R14,R13,R12,R11,R10, R9, R8,  R7  ,  R6  ,  R5   ,  R4  , R3, R2, R1, R0
1452
1453 example : `PUSHM #6,IP` pushes IP,S,T,W,X,Y registers to return stack
1454
1455     POPM  order :  PC,RSP, SR, R3,rDOCOL,rDODOES,rDOCON,rDOVAR, Y , X , W , T , S , IP,TOS,PSP
1456     POPM  order :  R0, R1, R2, R3,  R4  ,  R5   ,  R6  ,   R7 , R8, R9,R10,R11,R12,R13,R14,R15
1457
1458 example : `POPM #6,IP` pulls Y,X,W,T,S,IP registers from return stack
1459
1460 Error occurs if #n is out of bounds.
1461
1462 **conditionnal jumps use**
1463
1464     0=    with IF UNTIL WHILE ?GOTO
1465     0<>   with IF UNTIL WHILE ?GOTO
1466     U>=   with IF UNTIL WHILE ?GOTO
1467     U<    with IF UNTIL WHILE ?GOTO
1468     S<    with IF UNTIL WHILE ?GOTO
1469     S>=   with IF UNTIL WHILE ?GOTO
1470     0>=   with IF UNTIL WHILE
1471     0<    with ?GOTO
1472
1473 # FAST FORTH resumed
1474
1475     RETURN-STACK-CELLS  = 48            max size of the return stack, in cells
1476     STACK-CELLS         = 48            max size of the data stack, in cells
1477     /COUNTED-STRING      = 255              max size of a counted string, in characters
1478     /HOLD                  = 34            size of the pictured numeric output string buffer, in characters
1479     /PAD                    = 84            size of the scratch area pointed to by PAD, in characters
1480     ADDRESS-UNIT-BITS   = 16            size of one address unit, in bits
1481     FLOORED              = true             true if floored division is the default
1482     MAX-CHAR            = 255           max value of any character in the implementation-defined character set
1483     MAX-N               = 32767         largest usable signed integer
1484     MAX-U               = 65535         largest usable unsigned integer
1485     MAX-D                  = 2147483647     largest usable signed double number
1486     MAX-UD              = 4294967295    largest usable unsigned double number
1487     DeFiNiTiOnS aRe CaSe-InSeNsItIvE    they are compiled in their CAPS_ON form.
1488
1489 ## FORTH word-set
1490
1491 Reduced to 53 definitions, but with everything necessary to be expandable up to $FF80.
1492
1493 RST_SET,
1494 RST_RET,
1495 [MARKER     ](https://forth-standard.org/standard/core/MARKER),
1496 HI2LO,
1497 CODENNM,
1498 HDNCODE,
1499 CODE,
1500 [IS         ](https://forth-standard.org/standard/core/IS),
1501 [\:NONAME   ](https://forth-standard.org/standard/core/ColonNONAME),
1502 [DOES>      ](https://forth-standard.org/standard/core/DOES),
1503 [CREATE     ](https://forth-standard.org/standard/core/CREATE),
1504 [IMMEDIATE  ](https://forth-standard.org/standard/core/IMMEDIATE),
1505 [;          ](https://forth-standard.org/standard/core/Semi),
1506 [:          ](https://forth-standard.org/standard/core/Colon),
1507 [POSTPONE   ](https://forth-standard.org/standard/core/POSTPONE),
1508 [\\         ](https://forth-standard.org/standard/core/bs),
1509 [\]         ](https://forth-standard.org/standard/core/right-bracket),
1510 [\[         ](https://forth-standard.org/standard/core/Bracket),
1511 [\[\'\]     ](https://forth-standard.org/standard/core/BracketTick),
1512 [\'         ](https://forth-standard.org/standard/core/Tick),
1513 [ABORT"     ](https://forth-standard.org/standard/core/ABORTq),
1514 [ALLOT      ](https://forth-standard.org/standard/core/ALLOT),
1515 [COUNT      ](https://forth-standard.org/standard/core/COUNT),
1516 [LITERAL    ](https://forth-standard.org/standard/core/LITERAL),
1517 [,          ](https://forth-standard.org/standard/core/Comma),
1518 [>NUMBER    ](https://forth-standard.org/standard/core/toNUMBER),
1519 [FIND       ](https://forth-standard.org/standard/core/FIND),
1520 [WORD       ](https://forth-standard.org/standard/core/WORD),
1521 [."         ](https://forth-standard.org/standard/core/Dotq),
1522 [S"         ](https://forth-standard.org/standard/core/Sq),
1523 [.          ](https://forth-standard.org/standard/core/d),
1524 [U.         ](https://forth-standard.org/standard/core/Ud),
1525 [SIGN       ](https://forth-standard.org/standard/core/SIGN),
1526 [HOLD       ](https://forth-standard.org/standard/core/HOLD),
1527 [#>         ](https://forth-standard.org/standard/core/num-end),
1528 [#S         ](https://forth-standard.org/standard/core/numS),
1529 [#          ](https://forth-standard.org/standard/core/num),
1530 [<#         ](https://forth-standard.org/standard/core/num-start),
1531 [\[UNDEFINED\]  ](https://forth-standard.org/standard/tools/BracketUNDEFINED),
1532 [\[DEFINED\]    ](https://forth-standard.org/standard/tools/BracketDEFINED),
1533 [\[IF\]         ](https://forth-standard.org/standard/tools/BracketIF),
1534 [\[THEN\]       ](https://forth-standard.org/standard/tools/BracketTHEN)
1535 [\[ELSE\]       ](https://forth-standard.org/standard/tools/BracketELSE),
1536 [!          ](https://forth-standard.org/standard/core/Store),
1537 [@          ](https://forth-standard.org/standard/core/Fetch),
1538 [TYPE       ](https://forth-standard.org/standard/core/TYPE),
1539 NOECHO,
1540 ECHO,
1541 [EMIT       ](https://forth-standard.org/standard/core/EMIT),
1542 [KEY        ](https://forth-standard.org/standard/core/KEY),
1543 [ACCEPT     ](https://forth-standard.org/standard/core/ACCEPT),
1544 SYS.
1545
1546 Words ACCEPT KEY EMIT are DEFERred definitions. ACCEPT doesn't use KEY.
1547
1548     RST_SET         defines the bound of the program memory protected against any PUC.
1549     RST_RET         removes all words defined after RST_SET.
1550     HI2LO           used to switch compilation from high level (FORTH) to low level (assembler).
1551     CODENNM         the assembler counterpart of :NONAME.
1552     CODE <name>     creates a definition written in assembler.
1553                     this defined <name> must be ended with ENDCODE unless COLON or LO2HI use.
1554     HDNCODE <name>  same as CODE but the definition is in the hidden word-set to be visible only in the assembly mode.
1555     NOECHO          disables display on the TERMINAL
1556     ECHO            enables display on the TERMINAL
1557     SYS             0 SYS | SYS   executes WARM
1558                     +n (odd) SYS  same,
1559                     +n (even) SYS does software RESET then executes WARM
1560                     -n SYS        same as +n (even) SYS, plus resets the program memory to its original state.
1561
1562 ### Other constants/addresses which are usable in any generic source_files.f
1563
1564 **All constants, variables and definitions included in \inc\any.pat files are usable by
1565 the assembler and also by the FORTH interpreter.**
1566
1567
1568 ## MSP430ASSEMBLER word-set (in the hidden word-set)
1569
1570 [ADD, ADD.B     ](http://www.ti.com/lit/ug/slau272d/slau272d.pdf#page=135),
1571 [ADDC, ADDC.B   ](http://www.ti.com/lit/ug/slau272d/slau272d.pdf#page=136),
1572 [AND, AND.B     ](http://www.ti.com/lit/ug/slau272d/slau272d.pdf#page=137),
1573 [BIC, BIC.B     ](http://www.ti.com/lit/ug/slau272d/slau272d.pdf#page=138),
1574 [BIS, BIS.B     ](http://www.ti.com/lit/ug/slau272d/slau272d.pdf#page=139),
1575 [BIT, BIT.B     ](http://www.ti.com/lit/ug/slau272d/slau272d.pdf#page=140),
1576 [CALL           ](http://www.ti.com/lit/ug/slau272d/slau272d.pdf#page=142),
1577 [CMP, CMP.B     ](http://www.ti.com/lit/ug/slau272d/slau272d.pdf#page=147),
1578 [DADD, DADD.B   ](http://www.ti.com/lit/ug/slau272d/slau272d.pdf#page=149),
1579 [MOV, MOV.B     ](http://www.ti.com/lit/ug/slau272d/slau272d.pdf#page=165),
1580 [PUSH, PUSH.B   ](http://www.ti.com/lit/ug/slau272d/slau272d.pdf#page=168),
1581 [RETI           ](http://www.ti.com/lit/ug/slau272d/slau272d.pdf#page=170),
1582 [RRA, RRA.B     ](http://www.ti.com/lit/ug/slau272d/slau272d.pdf#page=173),
1583 [RRC, RRC.B     ](http://www.ti.com/lit/ug/slau272d/slau272d.pdf#page=174),
1584 [SUB, SUB.B     ](http://www.ti.com/lit/ug/slau272d/slau272d.pdf#page=179),
1585 [SUBC, SUBC.B   ](http://www.ti.com/lit/ug/slau272d/slau272d.pdf#page=180),
1586 [SWPB           ](http://www.ti.com/lit/ug/slau272d/slau272d.pdf#page=181),
1587 [SXT            ](http://www.ti.com/lit/ug/slau272d/slau272d.pdf#page=182),
1588 [XOR, XOR.B     ](http://www.ti.com/lit/ug/slau272d/slau272d.pdf#page=184),
1589 [RRUM           ](http://www.ti.com/lit/ug/slau272d/slau272d.pdf#page=218),
1590 [RLAM           ](http://www.ti.com/lit/ug/slau272d/slau272d.pdf#page=208),
1591 [RRAM           ](http://www.ti.com/lit/ug/slau272d/slau272d.pdf#page=211),
1592 [RRCM           ](http://www.ti.com/lit/ug/slau272d/slau272d.pdf#page=214),
1593 [POPM           ](http://www.ti.com/lit/ug/slau272d/slau272d.pdf#page=204),
1594 [PUSHM          ](http://www.ti.com/lit/ug/slau272d/slau272d.pdf#page=205),
1595 ?GOTO,
1596 GOTO,
1597 BW3,
1598 BW2,
1599 BW1,
1600 FW3,
1601 FW2,
1602 FW1,
1603 REPEAT,
1604 WHILE,
1605 AGAIN,
1606 UNTIL,
1607 ELSE,
1608 THEN,
1609 IF,
1610 0=,
1611 0<>,
1612 U>=,
1613 U<,
1614 0<,
1615 0>=,
1616 S<,
1617 S>=,
1618 LO2HI,
1619 COLON,
1620 ENDCODE.
1621
1622     ?GOTO           used after a conditionnal (0=,0<>,U>=,U<,0<,S<,S>=) to branch to a label FWx or BWx
1623     GOTO            used as unconditionnal branch to a label FWx or BWx
1624     BW3             BACKWARD branch destination n°3
1625     BW2                                         n°2
1626     BW1                                         n°1
1627     FW3             FORWARD branch destination  n°3
1628     FW2                                         n°2
1629     FW1                                         n°1
1630     REPEAT          assembler version of the FORTH word REPEAT
1631     WHILE           idem
1632     AGAIN           idem
1633     UNTIL           idem
1634     ELSE            idem
1635     THEN            idem
1636     IF              idem
1637     0=              conditionnal
1638     0<>             conditionnal
1639     U>=             conditionnal
1640     U<              conditionnal
1641     0<              conditionnal, to use only with ?GOTO
1642     0>=             conditionnal, to use only with IF UNTIL WHILE
1643     S<              conditionnal
1644     S>=             conditionnal
1645     LO2HI           switches compilation from low level to high level modes without saving IP register.
1646     COLON           pushes IP then performs LO2HI.
1647     ENDCODE         to end a CODE or HDNCODE definition.
1648
1649 #### EXTENDED_MEM WORDS set:
1650
1651 Gives access to addresses beyond $FFFF
1652
1653 [POPM.A         ](http://www.ti.com/lit/ug/slau272d/slau272d.pdf#page=204),
1654 [PUSHM.A        ](http://www.ti.com/lit/ug/slau272d/slau272d.pdf#page=205),
1655 [ADDA           ](http://www.ti.com/lit/ug/slau272d/slau272d.pdf#page=229),
1656 [CALLA          ](http://www.ti.com/lit/ug/slau272d/slau272d.pdf#page=232),
1657 [CMPA           ](http://www.ti.com/lit/ug/slau272d/slau272d.pdf#page=235),
1658 [MOVA           ](http://www.ti.com/lit/ug/slau272d/slau272d.pdf#page=238),
1659 [SUBA           ](http://www.ti.com/lit/ug/slau272d/slau272d.pdf#page=241)
1660
1661 #### EXTENDED_ASM WORDS set:
1662
1663 Full 20 bits address/data assembler
1664
1665 [ADDX, ADDX.A, ADDX.B   ](http://www.ti.com/lit/ug/slau272d/slau272d.pdf#page=187),
1666 [ADDCX, ADDCX.A, ADDCX.B](http://www.ti.com/lit/ug/slau272d/slau272d.pdf#page=188),
1667 [ANDX ANDX.A, ANDX.B    ](http://www.ti.com/lit/ug/slau272d/slau272d.pdf#page=189),
1668 [BICX, BICX.A, BICX.B   ](http://www.ti.com/lit/ug/slau272d/slau272d.pdf#page=190),
1669 [BISX, BISX.A, BISX.B   ](http://www.ti.com/lit/ug/slau272d/slau272d.pdf#page=191),
1670 [BITX, BITX.A, BITX.B   ](http://www.ti.com/lit/ug/slau272d/slau272d.pdf#page=192),
1671 [CMPX, CMPX.A, CMPX.B   ](http://www.ti.com/lit/ug/slau272d/slau272d.pdf#page=194),
1672 [DADDX, DADDX.A, DADDX.B](http://www.ti.com/lit/ug/slau272d/slau272d.pdf#page=196),
1673 [MOVX, MOVX.A, MOVX.B   ](http://www.ti.com/lit/ug/slau272d/slau272d.pdf#page=202),
1674 [PUSHX, PUSHX.A, PUSHX.B](http://www.ti.com/lit/ug/slau272d/slau272d.pdf#page=207),
1675 [RRAX, RRAX.A, RRAX.B   ](http://www.ti.com/lit/ug/slau272d/slau272d.pdf#page=212),
1676 [RRCX, RRCX.A, RRCX.B   ](http://www.ti.com/lit/ug/slau272d/slau272d.pdf#page=216),
1677 [RRUX, RRUX.A, RRUX.B   ](http://www.ti.com/lit/ug/slau272d/slau272d.pdf#page=219),
1678 [SUBX, SUBX.A, SUBX.B   ](http://www.ti.com/lit/ug/slau272d/slau272d.pdf#page=221),
1679 [SUBCX, SUBCX.A, SUBCX.B](http://www.ti.com/lit/ug/slau272d/slau272d.pdf#page=222),
1680 [SWPBX, SWPBX.A         ](http://www.ti.com/lit/ug/slau272d/slau272d.pdf#page=223),
1681 [SXTX, SXTX.A           ](http://www.ti.com/lit/ug/slau272d/slau272d.pdf#page=225),
1682 [XORX, XORX.A, XORX.B   ](http://www.ti.com/lit/ug/slau272d/slau272d.pdf#page=227),
1683 [RPT                    ](http://www.ti.com/lit/ug/slau272d/slau272d.pdf#page=119)
1684
1685 ### VOCABULARY ADD-ON
1686
1687 [DEFINITIONS     ](https://forth-standard.org/standard/search/DEFINITIONS),
1688 [PREVIOUS        ](https://forth-standard.org/standard/search/PREVIOUS),
1689 ONLY,
1690 FORTH,
1691 WORDSET.
1692
1693     FORTH               adds FORTH as first CONTEXT word-set
1694     FORTH ONLY          clears the CONTEXT stack, same as `-1 SYS`
1695     WORDSET <name>      creates a new word-set named <name>
1696     <name>              adds this named word-set in the CONTEXT stack
1697
1698
1699 ### SD_CARD_LOADER ADD-ON
1700
1701     LOAD" SD_TEST.4TH"  loads source file SD_TEST.4TH from SD_Card and compile it.
1702     BOOT                enable bootstrap
1703     NOBOOT              disable bootstrap
1704
1705 Once bootloader is enabled, any PUC event loads (and executes) the file \BOOT.4TH from the SD_Card.
1706
1707 ### SD_CARD_READ_WRITE ADD-ON
1708
1709     TERM2SD"        TERM2SD" SD_TEST.4TH" copy SD_TEST.4TH file to SD_CARD (use CopySourceFileToTarget_SD_Card.bat to do)
1710     WRITE           write sequentially the content of SD_buf to a file
1711     READ            read sequentially a file in SD_buf, leave a flag, false when the file is automatically closed.
1712     CLOSE           close last opened file.
1713     DEL" TRUC"      remove quietly the file TRUC from SD_CARD.
1714     WRITE" TRUC"    create or overwrite a file TRUC ready to write to its beginning.
1715     APPEND" TRUC"   open or create a file TRUC ready to write to the end of this file
1716     READ" TRUC"     open TRUC and load its first sector in SD_buf
1717     WR_SECT         Write SD_BUF in Sector loaded in  W=lo:X=hi
1718     RD_SECT         Read Sector W=lo:X=hi into SD_BUF, set BufferPtr=0
1719
1720
1721 ## OPTIONNAL ADD-ON
1722
1723 * Their respective MARKER word identified with braces {} removes all subsequent words.
1724   Sources are in the folder \MSP430-FORTH\, as source.f file.
1725
1726 ### ANS_COMP
1727
1728 Adds complement to pass FORTH ANS94 core test.
1729
1730 [VALUE      ](https://forth-standard.org/standard/core/VALUE),
1731 [TO         ](https://forth-standard.org/standard/core/TO),
1732 [DEFER      ](https://forth-standard.org/standard/core/DEFER),
1733 [BEGIN      ](https://forth-standard.org/standard/core/BEGIN),
1734 [SPACES     ](https://forth-standard.org/standard/core/SPACES),
1735 [SPACE      ](https://forth-standard.org/standard/core/SPACE),
1736 [BL         ](https://forth-standard.org/standard/core/BL),
1737 [PAD        ](https://forth-standard.org/standard/core/PAD),
1738 [>IN        ](https://forth-standard.org/standard/core/toIN),
1739 [BASE       ](https://forth-standard.org/standard/core/BASE),
1740 [STATE      ](https://forth-standard.org/standard/core/STATE),
1741 [CONSTANT   ](https://forth-standard.org/standard/core/CONSTANT),
1742 [VARIABLE   ](https://forth-standard.org/standard/core/VARIABLE),
1743 [SOURCE     ](https://forth-standard.org/standard/core/SOURCE),
1744 [RECURSE    ](https://forth-standard.org/standard/core/RECURSE),
1745 [EVALUATE   ](https://forth-standard.org/standard/core/EVALUATE),
1746 [EXECUTE    ](https://forth-standard.org/standard/core/EXECUTE),
1747 [>BODY      ](https://forth-standard.org/standard/core/toBODY),
1748 [.(         ](https://forth-standard.org/standard/core/Dotp),
1749 [(          ](https://forth-standard.org/standard/core/p),
1750 [DECIMAL    ](https://forth-standard.org/standard/core/DECIMAL),
1751 [HEX        ](https://forth-standard.org/standard/core/HEX),
1752 [HERE       ](https://forth-standard.org/standard/core/HERE),
1753 [FILL       ](https://forth-standard.org/standard/core/FILL),
1754 [MOVE       ](https://forth-standard.org/standard/core/MOVE),
1755 [+!         ](https://forth-standard.org/standard/core/PlusStore),
1756 [[CHAR]     ](https://forth-standard.org/standard/core/BracketCHAR),
1757 [CHAR       ](https://forth-standard.org/standard/core/CHAR),
1758 [CELL+      ](https://forth-standard.org/standard/core/CELLPlus),
1759 [CELLS      ](https://forth-standard.org/standard/core/CELLS),
1760 [CHAR+      ](https://forth-standard.org/standard/core/CHARPlus),
1761 [CHARS      ](https://forth-standard.org/standard/core/CHARS),
1762 [ALIGN      ](https://forth-standard.org/standard/core/ALIGN),
1763 [ALIGNED    ](https://forth-standard.org/standard/core/ALIGNED),
1764 [2OVER      ](https://forth-standard.org/standard/core/TwoOVER),
1765 [2SWAP      ](https://forth-standard.org/standard/core/TwoSWAP),
1766 [2DROP      ](https://forth-standard.org/standard/core/TwoDROP),
1767 [2DUP       ](https://forth-standard.org/standard/core/TwoDUP),
1768 [2!         ](https://forth-standard.org/standard/core/TwoStore),
1769 [2@         ](https://forth-standard.org/standard/core/TwoFetch),
1770 [R@         ](https://forth-standard.org/standard/core/RFetch),
1771 [ROT        ](https://forth-standard.org/standard/core/ROT),
1772 [OVER       ](https://forth-standard.org/standard/core/OVER),
1773 [*/         ](https://forth-standard.org/standard/core/TimesDiv),
1774 [*/MOD      ](https://forth-standard.org/standard/core/TimesDivMOD),
1775 [MOD        ](https://forth-standard.org/standard/core/MOD),
1776 [/          ](https://forth-standard.org/standard/core/Div),
1777 [/MOD       ](https://forth-standard.org/standard/core/DivMOD),
1778 [*          ](https://forth-standard.org/standard/core/Times),
1779 [FM/MOD     ](https://forth-standard.org/standard/core/FMDivMOD),
1780 [ABS        ](https://forth-standard.org/standard/core/ABS),
1781 [NEGATE     ](https://forth-standard.org/standard/core/NEGATE),
1782 [SM/REM     ](https://forth-standard.org/standard/core/SMDivREM),
1783 [UM/MOD     ](https://forth-standard.org/standard/core/UMDivMOD),
1784 [M*         ](https://forth-standard.org/standard/core/MTimes),
1785 [UM*        ](https://forth-standard.org/standard/core/UMTimes),
1786 [2/         ](https://forth-standard.org/standard/core/TwoDiv),
1787 [2*         ](https://forth-standard.org/standard/core/TwoTimes),
1788 [MIN        ](https://forth-standard.org/standard/core/MIN),
1789 [MAX        ](https://forth-standard.org/standard/core/MAX),
1790 [RSHIFT     ](https://forth-standard.org/standard/core/RSHIFT),
1791 [LSHIFT     ](https://forth-standard.org/standard/core/LSHIFT),
1792 [INVERT     ](https://forth-standard.org/standard/core/INVERT),
1793 [1-         ](https://forth-standard.org/standard/core/OneMinus),
1794 [1+         ](https://forth-standard.org/standard/core/OnePlus),
1795 [S>D        ](https://forth-standard.org/standard/core/StoD),
1796 [XOR        ](https://forth-standard.org/standard/core/XOR),
1797 [OR         ](https://forth-standard.org/standard/core/OR),
1798 [AND        ](https://forth-standard.org/standard/core/AND),
1799 [LEAVE      ](https://forth-standard.org/standard/core/LEAVE),
1800 [UNLOOP     ](https://forth-standard.org/standard/core/UNLOOP),
1801 [J          ](https://forth-standard.org/standard/core/J),
1802 [I          ](https://forth-standard.org/standard/core/I),
1803 [+LOOP      ](https://forth-standard.org/standard/core/PlusLOOP),
1804 [LOOP       ](https://forth-standard.org/standard/core/LOOP),
1805 [DO         ](https://forth-standard.org/standard/core/DO),
1806 [REPEAT     ](https://forth-standard.org/standard/core/REPEAT),
1807 [WHILE      ](https://forth-standard.org/standard/core/WHILE),
1808 [AGAIN      ](https://forth-standard.org/standard/core/AGAIN),
1809 [UNTIL      ](https://forth-standard.org/standard/core/UNTIL),
1810 [THEN       ](https://forth-standard.org/standard/core/THEN),
1811 [ELSE       ](https://forth-standard.org/standard/core/ELSE),
1812 [IF         ](https://forth-standard.org/standard/core/IF),
1813 [>          ](https://forth-standard.org/standard/core/more),
1814 [<          ](https://forth-standard.org/standard/core/less),
1815 [U<         ](https://forth-standard.org/standard/core/Uless),
1816 [=          ](https://forth-standard.org/standard/core/Equal),
1817 [0<         ](https://forth-standard.org/standard/core/Zeroless),
1818 [0=         ](https://forth-standard.org/standard/core/ZeroEqual),
1819 [C,         ](https://forth-standard.org/standard/core/CComma),
1820 [C!         ](https://forth-standard.org/standard/core/CStore),
1821 [C@         ](https://forth-standard.org/standard/core/CFetch),
1822 [R>         ](https://forth-standard.org/standard/core/Rfrom),
1823 [>R         ](https://forth-standard.org/standard/core/toR),
1824 [NIP        ](https://forth-standard.org/standard/core/NIP),
1825 [DROP       ](https://forth-standard.org/standard/core/DROP),
1826 [SWAP       ](https://forth-standard.org/standard/core/SWAP),
1827 [DEPTH      ](https://forth-standard.org/standard/core/DEPTH),
1828 [EXIT       ](https://forth-standard.org/standard/core/EXIT),
1829 [?DUP       ](https://forth-standard.org/standard/core/qDUP),
1830 [DUP        ](https://forth-standard.org/standard/core/DUP),
1831 [-          ](https://forth-standard.org/standard/core/Minus),
1832 [+          ](https://forth-standard.org/standard/core/Plus),
1833 [CR         ](https://forth-standard.org/standard/core/CR).
1834
1835
1836 ### FIXPOINT
1837
1838 S>F,
1839 F.,
1840 F*,
1841 F#S,
1842 F/,
1843 F-,
1844 F+,
1845 [HOLDS          ](https://forth-standard.org/standard/core/HOLDS).
1846
1847     S>F             u/n -- Qlo Qhi       convert u/n in a Q15.16 value
1848     F.              display a Q15.16 value
1849     F*              Q15.16 multiplication
1850     F#S             Qlo Qhi u -- Qhi 0
1851                     convert fractionnal part of a Q15.16 value displaying u digits
1852     F/              Q15.16 division
1853     F-              Q15.16 soustraction
1854     F+              Q15.16 addition
1855
1856
1857 ### UTILITY
1858
1859 [DUMP           ](https://forth-standard.org/standard/tools/DUMP),
1860 [U.R            ](https://forth-standard.org/standard/core/UDotR),
1861 [WORDS          ](https://forth-standard.org/standard/tools/WORDS),
1862 [?              ](https://forth-standard.org/standard/tools/q),
1863 [.S             ](https://forth-standard.org/standard/tools/DotS),
1864 .RS.
1865
1866     .RS             displays Return Stack content
1867
1868 ### SD_TOOLS
1869
1870     DIR             dump first sector of current directory
1871     FAT             dump first sector of FAT1
1872     CLUSTER.        .123 CLUSTER. displays first sector of cluster 123
1873     SECTOR.         .123456789 SECTOR. displays sector 123456789
1874
1875 ### DOUBLE word set (ANS94 compliant)
1876
1877 [D.R             ](https://forth-standard.org/standard/double/DDotR),
1878 [2LITERAL        ](https://forth-standard.org/standard/double/TwoLITERAL),
1879 [2VALUE          ](https://forth-standard.org/standard/double/TwoVALUE),
1880 [2CONSTANT       ](https://forth-standard.org/standard/double/TwoCONSTANT),
1881 [2VARIABLE       ](https://forth-standard.org/standard/double/TwoVARIABLE),
1882 [M*/             ](https://forth-standard.org/standard/double/MTimesDiv),
1883 [DMIN            ](https://forth-standard.org/standard/double/DMIN),
1884 [DMAX            ](https://forth-standard.org/standard/double/DMAX),
1885 [D2*             ](https://forth-standard.org/standard/double/DTwoTimes),
1886 [D2/             ](https://forth-standard.org/standard/double/DTwoDiv),
1887 [DABS            ](https://forth-standard.org/standard/double/DABS),
1888 [DNEGATE         ](https://forth-standard.org/standard/double/DNEGATE),
1889 [D-              ](https://forth-standard.org/standard/double/DMinus),
1890 [M+              ](https://forth-standard.org/standard/double/MPlus),
1891 [D+              ](https://forth-standard.org/standard/double/DPlus),
1892 [DU<             ](https://forth-standard.org/standard/double/DUless),
1893 [D<              ](https://forth-standard.org/standard/double/Dless),
1894 [D=              ](https://forth-standard.org/standard/double/DEqual),
1895 [D0<             ](https://forth-standard.org/standard/double/DZeroless),
1896 [D0=             ](https://forth-standard.org/standard/double/DZeroEqual),
1897 [D>S             ](https://forth-standard.org/standard/double/DtoS),
1898 [2ROT            ](https://forth-standard.org/standard/double/TwoROT),
1899 [D.              ](https://forth-standard.org/standard/double/Dd),
1900 [2R>             ](https://forth-standard.org/standard/core/TwoRfrom),
1901 [2R@             ](https://forth-standard.org/standard/core/TwoRFetch),
1902 [2>R             ](https://forth-standard.org/standard/core/TwotoR)
1903
1904
1905 ## IDE for linux UBUNTU
1906
1907 First search from ti.com: [MSP430Flasher](http://software-dl.ti.com/msp430/msp430_public_sw/mcu/msp430/MSP430Flasher/latest/index_FDS.html)
1908
1909 untar in a home folder then:
1910 * set executable flag in permission of this file
1911 * open MSPFlasher-1.3.16-linux-x64-installer.run
1912 * install in MSP430Flasher (under home)
1913
1914 open a terminal in MSP430Flasher/Drivers:
1915     sudo ./msp430uif_install.sh
1916
1917 copy MSP430Flasher/MSP430Flasher to /usr/local/bin/MSP430Flasher
1918 copy MSP430Flasher/libmsp430.so  to /usr/local/lib/MSP430Flasher/libmsp430.so
1919
1920 open an editor as superuser in /etc/ld.so.conf.d/
1921      write on first line (of new file): /usr/local/lib/msp430flasher/
1922      save this new file as libmsp430.conf
1923 then in a terminal: sudo /sbin/ldconfig
1924
1925
1926 #### install the package srecord
1927
1928 install the package scite
1929 as super user, edit /etc/scite/SciTEGlobal.properties
1930 uncomment (line 18): position.maximize=1
1931 uncomment (line 257): properties.directory.enable=1
1932 add line 7: PLAT_WIN=0
1933 add line 8: PLAT_GTK=1
1934 save file
1935
1936 at the end of your ~.profile file, add these two lines:
1937 FF="/the_root_of_your_FastForth_local_copy"
1938 export FF
1939
1940 https://sourceforge.net/projects/gema/files/gema/gema-1.4-RC/gema-1.4RC-src.tgz/download
1941 untar in a home folder then:
1942 make (ignore warnings)
1943 sudo make install (ignore warnings)
1944 make clean
1945 result in: /usr/local/bin/gema
1946
1947 http://john.ccac.rwth-aachen.de:8000/ftp/as/source/c_version/asl-current.tar.gz
1948 untar in a home folder then:
1949 copy /Makefile.def-samples/Makefile.def-i386-unknown-linux2.x,x to ../Makefile.def
1950 edit this Makefile.def to remove "-march=i586" option from line 7 (if any)
1951 make
1952 make test
1953 sudo make install
1954 make clean
1955 result: asl files are in /usr/local
1956
1957
1958 #### install minicom package
1959
1960
1961 sudo gpasswd --add ${USER} dialout
1962
1963 copy /config/msp430/.minirc.dfl in your home directory.
1964
1965 In /inc/RemoveComments.pat, deselect windows part, select linux part.
1966
1967
1968 With scite editor you can
1969    - assemble FastForth then download it to eZFET target,
1970    - edit your source files
1971    - preprocess file.f to file.4th
1972
1973 With minicom you can send a file.4th to your target via dev/ttyUSB0, up to 4Mbauds:
1974 CTRL_A + Y to send a file
1975
1976
1977