README.md

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