Across¶

Can you explain how Mecrisp-Across works in more detail, and keep it simple ?

How about a bit more complex ?

Host MCU Requirements¶

Mecrisp-Across is a emulator

Amount of RAM is the biggest hurdle, it needs a big chunk in one piece, but 128 kb should do, the largest buffer in use has 64 kb and then there are several smaller ones.
The tether connection is bit-banged in GPIO, easy to port, but timing is critical.

Hosts¶

STM32F4 Discovery board with STM32F407 MCU¶

Recommended for Mecrisp-Across V0.9 with the latest facilities, see here for details.

Ti Tiva board with tm4c1294 MCU¶

Not recommended unless you must have working Ethernet. Will not run V-0.9. see here for details

Tether-less Linux ARM device¶

Such as the Raspberry Pi.

Use the:

mecrisp-across-0.9a-experimental/mecrisp-stellaris-linux-with-mecrisp-across

image which is a “ELF 32-bit LSB executable, ARM, EABI5 version 1 (GNU/Linux), statically linked, stripped” file.

I haven’t tried it on any of my RPI’s but I expect it will work much like the “PC or Laptop” version below.

PC or Laptop¶

Linux or FreeBSD.

Mecrisp-Across also supports a tether-less Linux Thumbulator or Qemu-Static so you can test it on a PC, compile a Forth program for the MSP430 and examine the assembly code quality. You can generate a binary for the MSP430 and flash that to a chip using a Ti FET trpe programmer board such as a MSP-EXP430G2 .

That’s right, you can run it on X86 right now, without either of the boards above. All you need to do is get the release tarball

See the release notes.

Running Mecrisp-Across on a PC¶

After uncompressing the Mecrisp-Across release run the mecrisp-across-0.9a-experimental/across executable. This will result in a terminal opening.

#mecrisp-across-0.9a-experimental% ./across

Mecrisp-Stellaris RA 2.6.1a for Linux by Matthias Koch
 ok.

A More Complex Description¶

Across is a EMULATOR, the Host (PC or Board) actually thinks that the Target is a chunk of Host ram. Because we are running the PC version, we can investigate what will happen with no HOST BOARD and no MSP430 Target present.

So no Host Board or Target are present here:

On the PC:

Warning

use mecrisp-across-0.9a at least. Don’t use V0.9, it has a bug that prevents “.” working.

:~/mecrisp-stellaris/mecrisp-across-0.9a-experimental% ./across

  Mecrisp-Stellaris RA 2.6.1a for Linux by Matthias Koch
  ok.

  target

  2 2 + . 4 ok.

  P1IN @ . 0 ok.
  $CAFE P1IN ! ok.

  P1IN @ hex. $CAFE  ok.

Because there is no Host Board or Target, P1IN is initally 0, the value of a PC ram location. After we save $CAFE to P1IN, it is retained. Had a Host Board and Target been present, the actual logic levels on Port 1 of the MSP430 would have been returned when we read it.

Actual Blinky Code Example:¶

No Host, no Target present. PC only.

Start the Mecrisp-Across Target (MSP430) program¶

target

Examine some of the Definitions¶

words

Address: 000076E0 Flags: --- --- --- Name: u.r
Address: 00007654 Flags: --- --- --- Name: .r
Address: 000075C4 Flags: --- --- --- Name: ud.r
Address: 00007550 Flags: --- --- --- Name: d.r
Address: 000073B4 Flags: --- --- --- Name: rtype
Address: 00007358 Flags: --- --- --- Name: u.
Address: 000072E4 Flags: --- --- --- Name: .
Address: 000071FC Flags: --- --- --- Name: d.
Address: 000070FC Flags: --- --- --- Name: ud.
Address: 00006F8C Flags: --- --- --- Name: (d.)
Address: 00006ED0 Flags: --- --- --- Name: #>
Address: 00006DB8 Flags: --- --- --- Name: #s
Address: 00006C6C Flags: --- --- --- Name: #
Address: 00006BB0 Flags: --- --- --- Name: sign
Address: 00006B08 Flags: --- --- --- Name: hold
Address: 00006AA0 Flags: --- --- --- Name: <#
Address: 00006A44 Flags: --- --- --- Name: output-base
Address: 000069F0 Flags: --- --- --- Name: hld
Address: 000069A0 Flags: --- --- 0-f Name: BUF
Address: 00006928 Flags: --- --- --- Name: BUF0
Address: 000068C4 Flags: --- --- 0-f Name: maximum-number-length
Address: 0000685C Flags: --- Inl 2-f Name: d0=
Address: 0000658C Flags: --- --- --- Name: type
Address: 000062EC Flags: --- --- --- Name: spaces
Address: 0000617C Flags: --- --- --- Name: hex.
Address: 00006088 Flags: --- --- --- Name: hex-digit-emit
Address: 00005F64 Flags: --- --- --- Name: .digit
Address: 00005E90 Flags: --- Inl --- Name: space
Address: 00005DC0 Flags: --- Inl --- Name: cr
Address: 00005C54 Flags: --- --- --- Name: uart-init
Address: 00005B8C Flags: --- Inl --- Name: emit
Address: 00005AC8 Flags: --- Inl --- Name: key
Address: 00005A5C Flags: --- Inl --- Name: emit?
Address: 000059F0 Flags: --- Inl --- Name: key?
Address: 00005984 Flags: --- Inl --- Name: reset
Address: 000058DC Flags: --- Inl --- Name: 16MHz
Address: 00005834 Flags: --- Inl --- Name: 12MHz
Address: 0000578C Flags: --- Inl --- Name: 8MHz
Address: 000056E4 Flags: --- Inl --- Name: 1MHz
Address: 00005694 Flags: --- --- 0-f Name: IE1
Address: 00005644 Flags: --- --- 0-f Name: IE2
Address: 000055F0 Flags: --- --- 0-f Name: IFG1
Address: 0000559C Flags: --- --- 0-f Name: IFG2
Address: 00005548 Flags: --- --- 0-f Name: P1IN
Address: 000054F4 Flags: --- --- 0-f Name: P1OUT
Address: 000054A0 Flags: --- --- 0-f Name: P1DIR
Address: 0000544C Flags: --- --- 0-f Name: P1IFG
Address: 000053F8 Flags: --- --- 0-f Name: P1IES
Address: 000053A4 Flags: --- --- 0-f Name: P1IE
Address: 00005350 Flags: --- --- 0-f Name: P1SEL
Address: 000052FC Flags: --- --- 0-f Name: P1REN
...

Test Program¶

This is a simple blinky (blinky1.fs) and the program can be uploaded with the result saved into a log file (blinky1.log.fs) on your pc using the following command.

mecrisp-across-0.9a-experimental % cat blinky1.fs | qemu-arm-static mecrisp-stellaris-linux-with-mecrisp-across > blinky1.log.fs

Put it in a shell script¶

#!/bin/sh
# run in mecrisp-across-0.9-experimental

cat ./blinky1.fs | qemu-arm-static mecrisp-stellaris-linux-with-mecrisp-across > blinky1.log.fs

blinky1.fs¶

\ MSP430 Blinky source for Mecrisp-Across - A Forth cross compiler for small MSP430 microcontrollers
\
\ mecrisp-across-0.9-experimental % cat blinky1.fs | qemu-arm-static mecrisp-stellaris-linux-with-mecrisp-across > blinky1.log.fs 
\ See blinky1.fs and blinky1.log.fs 

target


: delay ( -- )
    65535 0 do loop
;

: minblink ( -- )
   1 p1dir c!
   begin
     1 p1out cxor! delay
   again
;

see delay

see minblink

host
$FFFE vector minblink crosscompile
 
disimage
hexdump

blinky1.fs.log¶

Mecrisp-Stellaris RA 2.6.1 for Linux by Matthias Koch
\ MSP430 Blinky source for Mecrisp-Across - A Forth cross compiler for small MSP430 microcontrollers  ok.
\  ok.
\ paste it into the terminal that you get when running "across" on your pc. I think there is a file load command somewhere  ok.
  ok.
target 
 ok.
 ok.
: delay ( -- ) ok.
    65535 0 do loop ok.
; ok.
 ok.
: minblink ( -- ) ok.
   1 p1dir c! ok.
   begin ok.
     1 p1out cxor! delay ok.
   again ok.
; ok.
 ok.
see delay 
: delay
00007784 : 0000 : $0000FFFF 
00007790 : 0000 : $00000000 
0000779C : 0000 : swap 
000077A8 : 0000 : >r 
000077B4 : 0000 : >r 
000077C0 : 0000 : <--   
000077F8 : 0000 : r> 
00007804 : 0000 : $00000001 
00007810 : 0000 : + 
0000781C : 0000 : r@ 
00007828 : 0000 : >r 
00007834 : 0000 : dup 
00007840 : 0000 : r> 
0000784C : 0000 : swap 
00007858 : 0000 : >r 
00007864 : 0000 : = 
00007870 : 0000 : 0-Branch $000077C0 
0000787C : 0000 : r> 
00007888 : 0000 : drop 
00007894 : 0000 : r> 
000078A0 : 0000 : drop 
000078AC : 0000 : ;
ok.
 ok.
see minblink 
: minblink
000078F8 : 0000 : $00000001 
00007904 : 0000 : $00000022 
00007910 : 0000 : c! 
0000791C : 0000 : <--   
00007954 : 0000 : $00000001 
00007960 : 0000 : $00000021 
0000796C : 0000 : cxor! 
00007978 : 0000 : delay 
00007984 : 0000 : Branch $0000791C 
00007990 : 0000 : ;
ok.
 ok.
host 
$FFFE vector minblink crosscompile 
Memory usage in Flash without vector table 36 bytes.
Memory usage in RAM   without stacks       0 bytes.
Required passes: 1 
 ok.
   ok.
disimage 
F800: 40B2  mov.w #5A80h, &120h
F802: 5A80  
F804: 0120  
F806: 4031  mov.w #280h, r1
F808: 0280  
F80A: 4034  mov.w #260h, r4
F80C: 0260  
F80E: 43D2  mov.b #1h, &22h
F810: 0022  
F812: E3D2  xor.b #1h, &21h
F814: 0021  
F816: 4307  mov.w #0h, r7
F818: 4338  mov.w #FFFFh, r8
F81A: 5317  add.w #1h, r7
F81C: 9807  cmp.w r8, r7
F81E: 23FD  jnz F81A
F820: 3FF8  jmp F812
F822: 3FFF  jmp F822

Memory usage in Flash without vector table 36 bytes.
Memory usage in RAM   without stacks       0 bytes.
 ok.
hexdump 
:10F80000B240805A20013140800234406002D2432D
:10F810002200D2E321000743384317530798FD2302
:10F82000F83FFF3FFFFFFFFFFFFFFFFFFFFFFFFF6F
:10FFF000FFFFFFFFFFFFFFFFFFFFFFFFFFFF00F817
:00000001FF
 ok.
  ok.
  ok.

The hexdump can be pasted into a file and later used to flash into a actual MSP430 target, using one of the FET type dev boards or programmer. Because this is the output from the compiler, errors will have been found in your forth source and corrected, so the heximage is a bootable binary that will work because the compiler made it.

Of course, the program design might not do what the author thought it would do ;-)

Nevertheless, this does show how you can compile a program for MSP430 just using a PC.

Clearly, the advantage of a INTERACTIVE tethered Forth are obvious for program development, so a STM32F407 Host board is highly recommended.