.. index:: muforth
 
> :ref:`What's New ?<new-projects>` < 
 
.. _muforth:
 
.. Created muforth.rst: Thu 23 Feb 2023 21:40:35 AEDT 
.. Full Path: /home/tp/mecrisp-unofficial-doc/muforth.rst 
.. Author Copyright 2023 by t.j.porter \<techman001@protonmail.com\>
.. Made by /home/tp/projects/scripts/makerst.sh -->/usr/local/bin/makerst 
.. license: MIT, please see COPYING 
 
Muforth
=======
https://muforth.nimblemachines.com/

Intro
-----
Muforth is a small, simple, fast, indirect-threaded code (ITC) Forth intended for use as a cross-compiler for microcontrollers and other embedded devices. It is written in C and its core is very portable. Because of its Forth nature, it is naturally extensible, scriptable, and customizable.

Unlike Mecrisp-Stellaris: which could be considered muforth’s main “competition” – muforth supports a tethered development model, where the dictionary names and all the interactive command processing live on the host, and only the code and data live on the target machine. This makes it possible to target very small devices with a few kilobytes of flash. In contrast, mecrisp needs at least 16 KiB of flash to be useful; 32 KiB is a more comfortable minimum. On the other hand, mecrisp is very polished and useful, while muforth is still a work-in-progress. ;-)

muforth is very well-suited to interactive coding, debugging, and exploration, and is a great tool for bringing up new hardware. It has support – in varying degrees of completeness – for a number of different architectures and chip families.


Build Muforth
--------------
On your *LINUX* or *OpenBSD* box.

Get Muforth
^^^^^^^^^^^
::

 git clone https://github.com/nimblemachines/muforth.git

Build the muforth executable
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
In the directory you cloned muforth above into :

1. cd src
2. ./configure.sh
3. make
	
.. note:: The configure script gives you some options.
	
The muforth executable remains in the src/ directory, but a symlink pointing to	it is placed into the mu/ directory, and that's where you should be when running muforth.

.. SEEALSO:: Recommended, when you have the repo, run 'git log' and read the whole story for a TON of insight into muforth!

.. _mu-on-rpi:

Mu on RPI
---------
if like me, you only have a FreeBSD Unix workstation, then muforth wont work with the FreeBSD USB system, which is *vital*, so I've built a very responsive muforth system on a RPI-3 but should run on anything with Raspbian Linux. All the files are om my DOC site at Sourceforge, see below. Just flash the raspbian-muforth-developer.img to a SD card and plug it in and you'll have a working ready to use muforth!

Readme
^^^^^^
::

 Terry Porter 23Feb2023, licensed under the MIT license
 OS: 2022-09-22-raspios-bullseye-armhf-lite.img
 This is a complete working and tested Muforth system: https://muforth.nimblemachines.com/
 Contains: a working Readdb for STM32F0xx: https://mecrisp-stellaris-folkdoc.sourceforge.io/svd2db-v1.html
 Board Used: Raspberry PI-3
   SSHD enabled at boot
   IP: Auto (DHCP Client)
   User/Password: tp/tp
 Files: Join all the files together then uncompress with 'unxz'

Join files and check checksum
-----------------------------
Run raspbian-muforth-developer.sh

Files
-----
::

 Contents:
 ├── raspbian-muforth-developer.img.000
 ├── raspbian-muforth-developer.img.001
 ├── raspbian-muforth-developer.img.002
 ├── raspbian-muforth-developer.img.003
 ├── raspbian-muforth-developer.img.004
 ├── raspbian-muforth-developer.img.005
 ├── raspbian-muforth-developer.img.006
 ├── raspbian-muforth-developer.img.007
 ├── raspbian-muforth-developer.img.008
 ├── raspbian-muforth-developer.img.009
 ├── raspbian-muforth-developer.img.010
 ├── raspbian-muforth-developer.img.md5
 ├── raspbian-muforth-developer.readme
 └── raspbian-muforth-developer.sh

Total raspbian-muforth-developer.img.XXX (md5): bfe33bdbd23f82e77f06c1877307cdd0

**Download the files from:** https://sourceforge.net/projects/mecrisp-stellaris-folkdoc/files/

.. warning:: delete the 'mu' sumlink in /home/tp as it became a circular link during my build process.

Raspian Notes
^^^^^^^^^^^^^

Package Manager
~~~~~~~~~~~~~~~
::
 
 apt search <package>
 apt install <package>
 apt info <package>
 apt remove <package>

Editor
~~~~~~
I installed VIM but have problems copying and pasting from it on my FreeBSD workstation via SSH. the editor Elvis however works fine and is VIM compatible.
::
 
 apt install elvis 
 apt remove vim
 apt autoremove

Updating Muforth
~~~~~~~~~~~~~~~~
In the /home/tp/muforth directory just enter 'git pull' to update to the latest Muforth commits.

*Recommended* Enter 'git log' and read the whole interesting development story.

Quickstart STM32F0 Disco Target
-------------------------------
On the RPI

Connect The Board
-----------------
Plug a STM32F0 Discovery board into RPI using the USB cable.


Load the board type
-------------------
Which includes a 'bling the green and blue leds once' blinky.
::

 ./muforth -f target/ARM/board/stm32f0-discovery.mu4

Output
^^^^^^
::

 muforth/64 (4f989340) 2021-jul-09 12:06 (https://muforth.nimblemachines.com/)
 Copyright (c) 2002-2021 David Frech (read the LICENSE for details)
 
 Type 'settings' to see a few of muforth's tweakable behaviours.
 
 (( STM32F0 Discovery board 
 (( STM32F051x8 chip 
 (( ARM Cortex-M0 processor 
 (( Target endianness ))
 (( ARM v6-M meta-compiler (target-specific chains) ))
 (( Meta-compiler (chains and token consumers) ))
 (( ARM v6-M memory image ))
 (( Reading Motorola S-record (S19) files ))
 (( ARM v6-M Thumb2 disassembler ))
 (( ARM v6-M Thumb2 assembler }} again.  4# again.  00r again.  i8 again.  sh-imm again.  ))
 (( ARM v6-M meta-compiler (main) ; again.  ))
 (( ARM v6-M interaction dumps again.  ))
 (( ARM v6-M Forth kernel (ITC) ))))))
 (( ST-LINK debug ST-LINK/V2 h* again.  ))))

Connect JTAG
------------
This connects the PC Muforth to the Board Muforth via JTAG (SWD over St-Link via USB) *AND* uploads a cutdown Muforth kernel to the Target.
::

 jtag

Output
^^^^^^
You are now talking to the Muforth on the Target in debug mode.
::

 ST-LINK/V2  JTAG v37 
 DFU mode => Mass mode => Debug mode 
       SP        RP        IP
 20000368  00000000  00000000*  Ok (chatting) (hex)


In this mode you can upload a file as below, examine registers, disassemble the compiled Muforth Words etc.

Example File
------------
loading the target/ARM/board/stm32f0-discovery.mu4 as above now loads the led blink example file as well. If you switch to the 'target' vocab you can see the blink words. The default blink only flashed each led once, it doesn't stay in a blinky loop or use a delay to blink them for a while .

Pressing the black RESET push button on the board will make the green and blue leds flash once and the muforth REPL seems to stay connected afterwards.
::

 target  Ok (chatting) (hex) (flash)
 words 
 
 flash-leds  wait  led-init  clock-init  wait-for-rdy  =  <  u<  0=  0<  c!+  c@+  !+  @+  clr!  set!  +!  c!  h!  !  c@  h@  @  bic  
 xor  or  and  *  +  -  u>>  >>  <<  u2/  2/  2*  negate  invert  @execute  execute  nope  
 (41 words) Ok (chatting) (hex) (flash)

Standalone
----------
You can press the reset button or remove the board and just apply power and the leds will briefly blink as the program is running from flash now in Turnkey mode.

Reconnect
---------
The board can be plugged back into the PC USB cable and 
::

 jtag

entered. At this point the PC Muforth should be talking to the Target Muforth once again.

.. warning:: The PC Muforth Target image must be the same as whats on the board or it won't work, but Muforth will warn you they're not the same.

to check, just enter 'verify' as below
::

 verify  Ok (chatting) (hex) (flash)


Testing Summary
---------------
Not good news I'm sorry to say as Mu experienced a *silent chat* issue that resulted in a register value being incorrect. Eventually I fixed it by repowering the target Disco board at least twice as the incorrect value had become 'locked in' for some reason.

I'd submit a issue to the author if I was sure of what had happened and I could easily repeat it, but for now I'll put Muforth in my 'Alpha category' and wait for it to mature some more before I try again.

.. seealso:: :ref:`Hosted Or Tether Part 2<hosted-or-tether-pt2>`