howto.md

   1
   2
   3     WHAT IS FAST FORTH FOR MSP430FR ?
   4     HARDWARE TO START
   5     FAST FORTH IS IT AN IDE ?
   6     HOW TO MIX ASSEMBLY and FORTH ?
   7     WRITING RULES
   8     ASSEMBLY WITHOUT LABEL ?
   9     SYMBOLIC ASSEMBLER ? YES !
  10     COMPILE FAST FORTH FOR YOUR MODULE
  11     START YOUR PROJECT
  12     Case of MSP430FR2xxx family (with FLL)
  13     ANNEXE
  14
  15 WHAT IS FAST FORTH FOR MSP430FRxxxx ?
  16 --
  17
  18 FAST FORTH is a FORTH program written in MSP430 assembly and it runs on TI's LAUNCHPAD :
  19 MSP-EXP430FR5739, MSP-EXP430FR5969, MSP-EXP430FR6989... or any MSP430 FRAM device.
  20 Its core is ANS FORTH standard compliant.
  21
  22 Built-in assembler allows you to program an application using interruptions and LPMX modes.
  23
  24 If you are beginner in FORTH, a vastefull literature is available on the web, try: http://www.forth.org/tutorials.html.
  25 Select "starting Forth" of Leo Brodie, that is sufficient for our purpose.
  26 In addition, as you can see in forthMSP430FR.asm, each FORTH word definition includes a reference to the ANS standard.
  27
  28
  29
  30 HARDWARE TO START
  31 --
  32
  33     a TI launchpad, the basic MSP-EXP430FR5969 or the MSP_EXP4305994 with SD card slot.
  34
  35     an UARTtoUSB cable with a PL2303TA (best choice) :
  36         Search :"PL2303TA"
  37         RX and TX wires are 3.3V level.
  38
  39         BE CAREFULL ! if you plan to supply your MSP430FRxxxx device with the PL2303TA cable,
  40         you MUST open it to weld the red wire (+) onto the 3.3V pad !!!
  41         otherwise, cut it...
  42
  43
  44     or UARTtoUSB bridge with CP2102 device :
  45         search on ebay :"UART to USB CP2102"
  46         Check for a 3.3V pin before paying !
  47
  48
  49 If you want to test RC5toLCD.f :
  50
  51     a standard LCD DISPLAY 2x16 or 2x20 chars,
  52     a VISHAY IR receiver TSOP32236 or equivalent plus an IR remote with RC5/RC6 Philips protocol,
  53     a piece of PCB to wire the diode, resistor and two capacitors of the LCD_Vo booster. See RC5toLCD.f
  54
  55 And to use the SD_Card extension :
  56
  57     http://www.ebay.com/itm/2-PCS-SD-Card-Module-Slot-Socket-Reader-For-Arduino-MCU-/181211954262?pt=LH_DefaultDomain_0&hash=item2a3112fc56
  58     http://fr.aliexpress.com/item/5V-3-3V-Compatible-Perfect-SD-Card-Module-Slot-Socket-Reader-For-ARM-MCU-Read/32223868267.html?isOrigTitle=true
  59
  60 It is not wasteful.
  61
  62
  63 I suggest you to wire constantly the RX0 TX0 pins of your LAUNCHPAD (RX1 TX1 pins for MSP-EXP430FR6989 launchpad) to a free USB socket on your PC via the cable UARTtoUSB PL2303TA.
  64 So you can drag and drop HEX file on MSP-EXP430FRxxxxprog.bat to regenerate FORTH kernel or download RC5toLCD.f without doing anything else...
  65
  66
  67 FAST FORTH IS IT AN IDE ?
  68 --
  69
  70 YES, if you admit that you can program in FORTH / in assembler, not C... Look at "RC5toLCD.f".
  71
  72 In fact, you have an IDE with two languages, one low level other high level, and it's easy to mix them.
  73
  74
  75 HOW TO MIX assembly and FORTH ?
  76 ---
  77
  78 FAST FORTH knows two kinds of words :
  79
  80     low level assembly words start with CODE <name> and end with ENDCODE.
  81
  82     high level FORTH words begin with : <name> and end with ;
  83
  84
  85 Examples
  86
  87     CODE ADD    \ Assembly word, alias of word +
  88         ADD @PSP+,TOS
  89         MOV @IP+,PC
  90     ENDCODE
  91
  92
  93     : NOOP      \ FORTH word, do nothing
  94         DUP
  95         DROP
  96     ;
  97
  98
  99
 100 To end a low level assembly word, the instruction MOV @IP+,PC jumps to the next FORTH word. This faster (4 cycles) and shorter (one word) instruction replaces the famous pair of assembly instructions : CALL #LABEL ... RET (4+4 cycles, 2+1 words). The register IP is the Interpretative Pointer.
 101
 102 High level FORTH word starts with a boot code DOCOL that save the IP pointer, load it with the first address of a list of execution addresses, then perform a postincrement branch to this first address. The list ends with the address of another piece of code EXIT (6 cycles) that restores IP before the instruction MOV @IP+,PC.
 103
 104
 105 here, the compilation of low level word ADD :
 106
 107                     preamble        \ compiled by the word CODE
 108     execution addr  ADD @PSP+,TOS
 109                     MOV @IP+,PC     \ instruction called NEXT
 110
 111 and the one of the high level word NOOP :
 112
 113                     preamble        \ compiled by the word :
 114     execution addr  PUSH IP         \ boot code compiled by the word :
 115                     CALL rEXIT      \ boot code compiled by the word :
 116                     addr of DUP     \ execution addr of DUP
 117                     addr of DROP    \ execution addr of DROP
 118                     addr of EXIT    \ execution addr of EXIT compiled by the word ;
 119
 120
 121 _A high level FORTH word is a list of execution addresses preceded by a boot code and ending with EXIT address._
 122
 123
 124 WRITING RULES
 125 --
 126
 127 any low level FORTH words must be ended with the instruction MOV @IP+,PC (NEXT).
 128
 129         CODE TEST               \ CODE starts a low level word
 130             asm1                \ assembly instruction 1
 131             asm2                \ assembly instruction 2
 132             MOV @IP+,PC         \ NEXT
 133         ENDCODE                 \ end of low level word
 134
 135
 136 If you want to use the IP register, save it before and restore it before NEXT
 137
 138         CODE TEST1              \ CODE starts a low level word
 139             asm1                \ assembly instructions
 140             ...
 141             PUSH IP             \ save IP before use
 142             MOV #1,IP           \ assembly instruction that uses IP
 143             ...                 \ assembly instructions
 144             MOV @RSP+,IP        \ restore IP
 145             MOV @IP+,PC         \ NEXT
 146         ENDCODE                 \ end of low level word
 147
 148
 149 A little more complex, the case of mixing FORTH and assembly that is enabled by the words HI2LO, LO2HI and COLON
 150
 151         : MIX_FORTH_ASM         \ definition of a FORTH word starts with :
 152             SWAP
 153             DUP
 154         HI2LO                   \ FORTH to assembler switch
 155             asm1                \ assembly instruction
 156             asm2                \ assembly instruction
 157             ...                 \ you can freely use IP !
 158             ...                 \ assembly instructions
 159             MOV @RSP+,IP        \ restore IP
 160             MOV @IP+,PC         \ NEXT
 161         ENDCODE                 \ end of low level word
 162
 163 If we see the code "MIX\_FORTH\_ASM" after compilation :
 164
 165             preamble            \ compiled by :
 166     exec@   PUSH IP             \ save IP compiled by :
 167             CALL rEXIT          \ execute EXIT compiled by :
 168             addr                \ execution addr of SWAP
 169             addr                \ execution addr of DUP
 170             next addr           \ addr of asm1, compiled by HI2LO
 171             asm1                \ assembly instruction
 172             asm2                \ assembly instruction
 173             ...                 \ you can freely use IP !
 174             ...                 \ assembly instructions
 175             MOV @RSP+,IP        \ restore IP saved by :
 176             MOV @IP+,PC         \ NEXT
 177
 178 the instruction "CALL rEXIT" (CALL R7), have EXIT address as rEXIT content.
 179
 180
 181 going a step further :
 182
 183         CODE MIX_ASM_FORTH      \ CODE starts a low level word
 184             asm1                \ assembly instruction 1
 185             asm2                \ assembly instruction 2
 186         COLON                   \ starts high level
 187             word1
 188             word2
 189         ;                       \ end of high level word
 190
 191
 192 If we see this code "MIX\_ASM\_FORTH" after compilation :
 193
 194             preamble            \ compiled by CODE
 195     exec@   asm1                \ assembly instruction 1
 196             asm2                \ assembly instruction 2
 197             PUSH IP             \ save IP compiled by COLON
 198             CALL rEXIT          \ execute EXIT compiled by COLON
 199             addr1               \ of word1
 200             addr2               \ of word2
 201             addr of EXIT        \ the word ; compiles EXIT that restores IP then executes MOV @IP+,PC
 202
 203
 204 EXIT is used twice !
 205
 206 the first time, at the start of FORTH word, after save IP:
 207
 208     EXIT    MOV @RSP+,IP    \ 2 pop into IP next PC pushed on return stack by CALL rEXIT
 209             MOV @IP+,PC     \ 4 execute the routine pointed by the the address next "CALL rEXIT"
 210
 211 then at the end of FORTH word :
 212
 213     EXIT    MOV @RSP+,IP    \ 2 pop old IP from return stack
 214             MOV @IP+,PC     \ 4 execute the routine pointed by the old IP
 215
 216
 217 A new step
 218
 219         : MIX_FORTH_ASM_FORTH   \ definition of a FORTH word starts with :
 220             word1
 221             word2
 222             ...
 223         HI2LO                   \ FORTH to assembler switch
 224             MOV #0,IP           \ IP is free for use
 225             asm1
 226             ...
 227         LO2HI                   \ assembler to FORTH switch
 228             word3
 229             word4
 230         ;                       \ end of high level word
 231
 232 the compiled result
 233
 234             preamble            \ compiled by :
 235     exec@   PUSH IP             \ save IP compiled by :
 236             CALL rEXIT          \ move next PC from return stack into IP, compiled by :
 237             addr1               \ of word1
 238             addr2               \ of word2
 239             ...
 240             next addr           \ compiled by HI2LO
 241             MOV #0,IP           \ IP is free for use
 242             asm1                \ assembly instruction
 243             ...
 244             CALL rEXIT          \ compiled by LO2HI (10 cycles switch)
 245             addr3               \ of word3
 246             addr4               \ of word4
 247             addr5               \ of EXIT
 248
 249 Still another step :
 250
 251         CODE MIX_ASM_FORTH_ASM  \ CODE starts a low level word
 252             asm1                \ assembly instruction
 253             asm2                \ assembly instruction
 254         COLON                   \ starts high level
 255             word
 256             ...
 257         HI2LO                   \ FORTH to assembler switch
 258             asm3                \ assembly instruction
 259             asm4                \ assembly instruction
 260             MOV @RSP+,IP        \ restore IP
 261             MOV @IP+,PC         \ NEXT
 262         ENDCODE                 \ end of low level word
 263
 264 In fact, an exclusive of FAST FORTH, the start of a word FORTH can be placed anywhere :
 265
 266         CODE MIX_ASM_FORTH_ASM_FORTH
 267             asm
 268             asm
 269             ...
 270         COLON                   \ starts high level
 271             word
 272             word
 273             ...
 274         HI2LO                   \ FORTH to assembler switch
 275             asm
 276             asm
 277            ...
 278         LO2HI                   \ assembler to FORTH switch
 279             word
 280             word
 281             ...
 282         ;                       \ end of high level word
 283
 284 with the compiled result :
 285
 286             preamble            \ compiled by CODE
 287     exec@   asm
 288             asm
 289             PUSH IP             \ compiled by COLON
 290             CALL rEXIT          \ compiled by COLON
 291             addr
 292             addr
 293             next address        \ compiled by HI2LO
 294             asm
 295             asm
 296             CALL rEXIT          \ compiled by LO2HI
 297             addr
 298             addr
 299             EXIT addr           \ that restores IP from return stack and then executes MOV @IP+,PC
 300
 301 As we see, IP is saved only once, it's logical.
 302
 303
 304 ASSEMBLY WITHOUT LABEL ?
 305 ---
 306
 307 Yes ! the assembly syntax borrows FORTH's one for jumps :
 308
 309     CODE TEST_IF_THEN
 310         CMP #1,R8           \ set Z,N,V, flags
 311         0= IF               \ irritating, the "IF =" upside down, isn't it?
 312             ADD R8,R9       \ true part of comparaison
 313         THEN
 314         ...                 \ the next
 315         MOV @IP+,PC         \ don't forget...
 316     ENDCODE                 \ don't forget...
 317
 318 and the complete version :
 319
 320     CODE TEST_IF_ELSE_THEN
 321         CMP #1,R8           \ set Z,N,V, flags
 322         0= IF               \
 323             ADD R8,R9       \ true part of comparaison
 324         ELSE
 325             SUB R8,R9       \ false part of comparaison
 326         THEN
 327         ...                 \ following for the two branches
 328         MOV @IP+,PC         \ don't forget...
 329     ENDCODE                 \ don't forget...
 330
 331 test for loop back version BEGIN ... UNTIL
 332
 333     CODE TEST_BEGIN_UNTIL
 334         MOV #8,R10
 335         BEGIN
 336             SUB #1,R10      \ set Z,N,V flags
 337         0= UNTIL            \ loop back to BEGIN if flag Z is set
 338         ...
 339         MOV @IP+,PC
 340     ENDCODE
 341
 342 test for out of loop version BEGIN ... WHILE ... REPEAT
 343
 344     CODE TEST_BEGIN_WHILE_REPEAT
 345         MOV #8,R10
 346         BEGIN
 347             SUB #1,R10      \ set Z,N,V flags
 348         0<> WHILE           \ go to out of loop if X=0 (Z flag =1)
 349             XOR #1,R9
 350         REPEAT              \ unconditionnal loop back to BEGIN
 351         ...                 \ out of loop here
 352         MOV @IP+,PC
 353     ENDCODE
 354
 355 infinite loop :
 356
 357     CODE TEST_BEGIN_AGAIN
 358         BEGIN
 359             ADD #1,R9
 360         AGAIN               \ unconditionnal loop back to BEGIN
 361     ENDCODE
 362
 363 to quit this infinite loop, press <reset>
 364
 365
 366 We can nest several conditional branches :
 367
 368     CODE TEST_NESTED_IF_ELSE
 369         CMP #0,R10
 370         0= IF
 371             CMP #0,R10
 372             0= IF
 373                 MOV #0,R11
 374             ELSE
 375                 SUB #1,R11
 376             THEN
 377         ELSE
 378             MOV #1,R11
 379         THEN
 380         MOV @IP+,PC
 381     ENDCODE
 382
 383 another nest :
 384
 385     CODE TEST_NESTED_BEGIN_AGAIN_IF
 386         MOV #8,R9
 387         BEGIN
 388             CMP #-1,R9
 389             0= IF
 390                 MOV @IP+,PC \ out of test_NESTED_BEGIN_AGAIN_IF
 391             THEN
 392             SUB #1,R9
 393         AGAIN
 394     ENDCODE
 395
 396
 397 you can also MIX conditional branches with a mix of FORTH/assembly :
 398
 399     see TEST5 in the demo file \MSP430-FORTH\TESTASM.4TH
 400
 401
 402 ...but not quite !
 403 ---
 404
 405 unconditionnal backward jump :
 406
 407         CODE UNCOND_BACKWARD
 408             asm
 409             asm
 410             JMP TEST        \ jump backward to the word TEST
 411         ENDCODE
 412
 413 conditionnal backward jump :
 414
 415         CODE COND_BACKWARD
 416             asm
 417             CMP #0,R8
 418             S< ?JMP TEST    \ jump backward to TEST if negative
 419             asm
 420             MOV @IP+,PC
 421         ENDCODE
 422
 423 FAST FORTH have one pass assembler, not able to make forward jump.
 424
 425 I have added possibility of several "non canonical" jumps, up to 3 backward and up to 3 forward imbricated jumps to label :
 426
 427     \ C UM/MOD   udlo|udhi u1 -- ur uq
 428     CODE UM/MOD
 429         MOV @PSP+,W     \ 2 W = DIVIDENDhi
 430         MOV @PSP,S      \ 2 S = DIVIDENDlo
 431     \ T.I. ROUTINE  Section 5.1.5 of MSP430 Family Application Reports
 432         MOV #0,Y        \ 1 CLEAR RESULT
 433         MOV #16,X       \ 2 INITIALIZE LOOP COUNTER
 434     BW1 CMP TOS,W       \ 1
 435         U< ?GOTO FW1    \ 2 if not carry
 436         SUB TOS,W       \ 1 if carry DIVIDENDhi-divisor
 437     FW1                 \   FW1 label is resolved therefore reusable
 438     BW2 ADDC Y,Y        \ 1 RLC quotient
 439         U>= ?GOTO FW1   \ 2 if carry Error: result > 16 bits
 440         SUB #1,X        \ 1 Decrement loop counter
 441         <0 ?GOTO FW2    \ 2 if 0< terminate w/o error
 442         ADD S,S         \ 1 RLA DIVIDENDlo
 443         ADDC W,W        \ 1 RLC DIVIDENDhi
 444         U< ?GOTO BW1    \ 2 if not carry    14~ loop
 445         SUB TOS,W       \ 1 if carry DIVIDENDhi-divisor
 446         BIS #1,SR       \ 1 SETC
 447         GOTO BW2        \ 2                 14~ loop
 448     FW2 BIC #1,SR       \ 1 CLRC  No error, C = 0
 449     FW1                 \  Error indication in C
 450     \ END T.I. ROUTINE  Section 5.1.5 of MSP430 Family Application Reports
 451         MOV W,0(PSP)    \ 3 remainder on stack
 452         MOV Y,TOS       \ 1 quotient in TOS
 453         MOV @IP+,PC     \ 4
 454     ENDCODE
 455
 456
 457 SYMBOLIC ASSEMBLER ? YES !
 458 --
 459
 460 I have discovered a little semantic preprocessor "GEMA", just like that FAST FORTH have its symbolic assembler !
 461
 462     \config\gema\MSP430FR_FastForth.pat contains variables FORTH for all devices
 463     \config\gema\MSP430FR57xx.pat contains declarations for FR57 family
 464     \config\gema\MSP430FR5x6x.pat ... for FR59/FR69 families
 465     \config\gema\MSP430FR2x4x.pat ... for FR2/FR4 families.
 466     \config\gema\DEVICE.pat contains memory map and vectors for a specified DEVICE
 467     \MSP430-FORTH\LAUNCHPAD.pat is the I/O config file for specific LAUNCHPAD or application
 468
 469 gema translates also FORTH registers in ASM registers (R0 to R15)
 470
 471 If you have created a network drive from your local gitlab directory, it's easy :
 472 with scite editor open a file.f, then select in the menu "tools" the items "preprocess..."
 473
 474 furnished examples : see \MSP430-FORTH\
 475 Enjoy !
 476
 477 Try SD\_TEST.f to build a SD\_Card test.
 478
 479
 480 COMPILE FAST FORTH FOR YOUR MODULE
 481 --
 482
 483 The principle is to create (or modify) first existing configuration files only to compile FAST FORTH.
 484
 485 1- in forthMSP430FR.asm "TARGET configuration SWITCHES"  create a line for your target, example:
 486
 487     ;MY_MSP430FR5738_1 ; compile for my own MSP430FR5738 miniboard
 488
 489 2- in Target.inc add one item:
 490
 491         .IFDEF MY_MSP430FR5738_1
 492         .warning "Code for MY_MSP430FR5738_1"
 493     DEVICE = "MSP430FR5738" ; for family.inc file below, defines your device
 494     ;CHIP  .equ 5738 ; not used
 495     UCA0_UART   ; for family.inc file below, defines uart used by FORTH input terminal
 496     LF_XTAL     ; for family.inc file below, defines if your module have a 32768 Hz xtal, to enable it.
 497     UCB0_SD     ; for family.inc file below, defines UC used for SD Card driver if used
 498         .include "MSP430FR57xx.inc"  ; include family declarations file: MSP430FR2x4x.inc, MSP430FR57xx.inc or MSP430FR5x6x.inc
 499         .ENDIF  ; MY_MSP430FR5738_1
 500
 501 3- complete family.inc file with declarations for your device if not exists.
 502    take care to verify they not already exist in common part at the end of the file.
 503
 504 4- include an item in TargetInit.asm:
 505     .IFDEF MY_MSP430FR5738_1
 506     .include "MSP430FR5738_1.asm"
 507     .ENDIF
 508
 509 5- create your target MSP430FR5738_1.asm from another target.asm as model, then customize declarations.
 510
 511
 512 6- if you use SD Card you must add an item in the forthMSP430FR_SD_INIT.asm file. Proceed as target.asm:
 513
 514         .IFDEF MY_MSP430FR5738_1
 515
 516     ; COLD default state : Px{DIR,SEL0,SEL1,SELC,IE,IFG,IV} = 0 ; PX{OUT,REN} = 1 ; Px{IN,IES} = ?
 517
 518     ; P2.3 as SD_CD
 519     SD_CD           .equ  08h
 520     SD_CDIN         .equ  P2IN
 521     ; P2.4 as SD_CS
 522     SD_CS           .equ  10h
 523     SD_CSOUT        .equ  P2OUT
 524
 525         BIS.B #SD_CS,&P2DIR ; SD_CS output high
 526
 527     ; P2.2/UCB0CLK                ---> SD_CardAdapter CLK (SCK)   default value
 528     ; P1.6/UCB0SIMO/UCB0SDA/TA0.0 ---> SD_CardAdapter SDI (MOSI)  default value
 529     ; P1.7/UCB0SOMI/UCB0SCL/TA1.0 <--- SD_CardAdapter SDO (MISO)  default value
 530         BIS #04C0h,&PASEL1  ; Configure UCB0 pins: P2.2 as UCB0CLK, P1.6 as UCB0SIMO & P1.7 as UCB0SOMI
 531                             ; P2DIR.x is controlled by eUSCI_B0 module
 532         BIC #04C0h,&PAREN   ; disable pullup resistors for SIMO/SOMI/CLK pins
 533
 534         .ENDIF
 535
 536 Then, for the needs of syntactic preprocessor:
 537
 538 1- create a \config\gema\device.pat file if not exist, from analog device.pat file
 539
 540 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
 541
 542 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
 543
 544
 545 START YOUR PROJECT
 546 --
 547
 548 How to start your project ?
 549
 550 I show you, assuming you are working from the scite editor with its enhanced tools menu.
 551
 552 First you create two files : project.f and test.f
 553
 554 PROJECT.f :
 555
 556     ; ----------------------------------------------------
 557     ; MSP430FR5969 MSP_EXP430FR5969 8MHZ 921600bds PROJECT
 558     ; ----------------------------------------------------
 559     WIPE        ; restore the content of your target.txt HEX file
 560
 561 here you append your already tested routines :
 562
 563     CODE FIRST  \ assembler CODE words are FORTH executable
 564         ...
 565     MOV @IP+,PC \ NEXT
 566     ENCODE
 567
 568     ASM TWO     \ assembler ASM words are not FORTH executable and can only be used in assembler mode
 569         ...     \ used to define interrupt routines, or subroutines as here.
 570     RET
 571     ENDASM
 572
 573     CODE THREE
 574         ...
 575     CALL #TWO   \ CALL only ASM words (finishing with RET(I))...
 576         ...
 577     MOV @IP+,PC \ NEXT
 578     ENCODE
 579
 580     ASM WDT_INT             \ interrupt routine
 581         ...
 582         ...
 583     BIC #WDTIFG,&SFRIFG1    \ reset WDT_INT flag
 584     BIC #$F8,0(RSP)         \ set CPU ON and GIE OFF in retiSR
 585     RETI                    \
 586     ENDASM
 587
 588     ;
 589
 590 then finish with this 2 "magic" words plus one optional : START, STOP and optional BACKGROUND
 591
 592     ASM BACKGROUND          \ (optional)
 593         ...                 \ insert here your background task
 594         ...
 595         ...
 596     MOV #(SLEEP),PC         \ Must be the last statement of BACKGROUND
 597     ENDASM                  \
 598
 599     CODE START              \ to init your app
 600         ...                 \ init assembly part
 601
 602
 603     MOV #SLEEP,X            \ redirect default background task to yours (optional)
 604     MOV #BACKGROUND,2(X)    \
 605
 606     COLON
 607         ...                 \ init FORTH part
 608
 609     \   NOECHO              \ uncomment if your app runs without terminal
 610         LIT RECURSE IS WARM \ insert START (so your init app) in the FORTH init process
 611         (WARM)              \ then continue the FORTH init process
 612     ;
 613
 614
 615     CODE STOP               \ to properly stop your app
 616         MOV #SLEEP,X        \ restore the default background (optional)
 617         MOV #(SLEEP),2(X)   \ (words SLEEP and (SLEEP) can only be used in assembler mode)
 618                             \ (thus "['] (SLEEP) IS SLEEP" don't works.)
 619     COLON
 620         ['] (WARM) IS WARM  \ remove START from FORTH init process
 621         ECHO                \ to retrieve FORTH input terminal
 622         COLD                \ reset CPU, interrupt vectors and restart FORTH.
 623     ;
 624
 625
 626                 ; compiling is done
 627     RST_HERE    ; thus allowing to restart your app with <reset> or COLD
 628     START       ; let's go!
 629
 630 end of file
 631
 632
 633 Each time you download this project file in LAUNCHPAD, the word WIPE returns the dictionary set as it was in TXT file.
 634 And the word RST_HERE protects the PROJECT against <RESET\>.
 635
 636 The word START allows to include your app init into FORTH's one.
 637 The word STOP unlink your app.
 638
 639 Look at the file RC5toLCD.f to retrieve this structure.
 640
 641
 642
 643 TEST.f :
 644
 645     \ ----------------------------------
 646     \ MSP-EXP430FR5969_8MHZ_TEST.f
 647     \ ----------------------------------
 648     RST_STATE   \ restore the state defined by PROJECT.f
 649
 650     here you write your routine to test
 651
 652     CODE TEST
 653     ...
 654     ...
 655     MOV @IP+,PC
 656     ENDCODE
 657
 658
 659     PWR_HERE    \ test.f content is protected against POWER OFF, but volatile with <reset>
 660
 661
 662
 663 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.
 664
 665 let's go
 666 --
 667
 668 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.
 669
 670 If the test don't work, modify it in the test.f file, then reload it.
 671
 672 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 !
 673
 674 Good luck !
 675
 676
 677
 678 Case of MSP430FR2xxx family (with FLL)
 679 ---
 680
 681
 682 Difficult to download CORETEST.4th on CHIPSTICK @ 8MHz without error (tested with USBtoUART device = CP2102).
 683
 684 To resolve, I was forced to speed the clock up to 8.29 MHz ! (see ChipStick_fr2433.inc)
 685
 686 And there is no this problem @ 16MHz !
 687
 688 Is a problem that affects this device only, or corrupt TLV area during welding?
 689
 690 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...
 691
 692
 693 ANNEXE
 694 --
 695
 696 The embedded assembler don't recognize the (useless) TI's symbolic addressing mode: ADD.B EDE,TONI.
 697
 698 REGISTERS correspondence
 699
 700     ASM     TI      FASTFORTH   comment
 701
 702     R0      PC      PC          Program Counter
 703     R1      SP      RSP         Return Stack Pointer
 704     R2      SR/CG1  SR          Status Register/Constant Generator 1
 705     R3      CG2                 Constant Generator 2
 706     R4      R4      rDODOES     contents address of xdodoes
 707     R5      R5      rDOCON      contents address of xdocon
 708     R6      R6      rDOVAR      contents address of RFROM
 709     R7      R7      rEXIT       contents address of EXIT
 710     R8      R8      Y           scratch register
 711     R9      R9      X           scratch register
 712     R10     R10     W           scratch register
 713     R11     R11     T           scratch register
 714     R12     R12     S           scratch register
 715     R13     R13     IP          Interpretation Pointer
 716     R14     R14     TOS         Top Of parameters Stack
 717     R15     R15     PSP         Parameters Stack Pointer
 718
 719     FASTFORTH registers must be preprocessed by gema.exe before sending to the embedded assembler.
 720     (don't use R3 and use R2 only with register addressing mode).
 721
 722 REGISTERS use
 723
 724     The FASTFORTH registers rDOCOL, rDOVAR, rDOCON and rDODOES must be preserved.
 725     PUSHM R13,R10 before use and POPM R10,R13 after.
 726
 727
 728 PARAMETERS STACK use
 729
 730     The register TOS (Top Of Stack) is the first cell of the Parameters stack.
 731     The register PSP (Parameters Stack Pointer) points the second cell.
 732
 733     to push one cell on the PSP stack :
 734
 735         SUB #2,PSP                  \ insert a empty 2th cell
 736         MOV TOS,0(PSP)              \ mov first cell in this empty 2th cell
 737         MOV <what you want>,TOS     \ or MOV.B <what you want>,TOS ; i.e. in first cell
 738         ...
 739
 740     to pop one cell from the PSP stack :
 741
 742         MOV @PSP+,TOS               \ first cell TOS is lost
 743         ...
 744
 745     don't never pop a byte with instruction MOV.B @PSP+, ...
 746
 747 RETURN STACK use
 748
 749     register RSP is the Return Stack Pointer (SP).
 750
 751     to push one cell on the RSP stack :
 752
 753         PUSH <what you want>        \
 754         ...
 755
 756     to pop one cell from the RSP stack :
 757
 758         MOV @RSP+,<where you want>   \
 759         ...
 760
 761     don't never pop a byte with instruction MOV.B @RSP+, ...
 762
 763
 764     to push multiple registers on the RSP stack :
 765
 766         PUSHM Rx,Ry                 \ x > y
 767         ...
 768
 769     to pop multiple registers from the RSP stack :
 770
 771         POPM Ry,Rx                  \ y < x
 772         ...
 773
 774 CPUx instructions PUSHM / POPM (my own syntax, not the TI's one, too bad :-)
 775
 776     PUSHM order : PSP,TOS,IP, S, T, W, X, Y, R7, R6, R5, R4
 777
 778     example : PUSHM IP,Y    \ push IP, S, T, W, X, Y registers onto the stack RSP
 779
 780
 781     POPM  order : R4, R5, R6, R7, Y, X, W, T, S, IP,TOS,PSP
 782
 783     example : POPM Y,IP     \ pop Y, X, W, T, S, IP registers from the stack RSP
 784
 785     error occurs if bad order (PUSHM Y,IP for example)
 786
 787
 788 CPUx instructions RRCM,RRAM,RLAM,RRUM
 789
 790     example : RRUM #3,R8      \ R8 register is Unsigned Right shifted by n=3
 791
 792     error occurs if 1 > n > 4
 793
 794
 795 conditionnal jumps use with symbolic assembler
 796
 797     0=    { IF UNTIL WHILE ?JMP ?GOTO }
 798     0<>   { IF UNTIL WHILE ?JMP ?GOTO }
 799     U>=   { IF UNTIL WHILE ?JMP ?GOTO }
 800     U<    { IF UNTIL WHILE ?JMP ?GOTO }
 801     S<    { IF UNTIL WHILE ?JMP ?GOTO }
 802     S>=   { IF UNTIL WHILE ?JMP ?GOTO }
 803     0>=   { IF UNTIL WHILE }
 804     0<    { ?JMP ?GOTO }
 805