README.md

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