.. index:: thumbulator, qemu, mecrisp-stellaris on your pc, pc, virtual mecrisp-stellaris


.. _thumbulator:

Thumbulator
===========

Thumbulator is a Thumb (16 bit ARM) instruction set simulator by dwelch67 https://github.com/dwelch67/thumbulator

Thumbulator is a simple alternative to QEMU/KVM etc.

.. note:: A modified Thumbulator is supplied and used with Mecrisp-Stellaris

Matthias makes use of a modified Thumbulator to build the binary image files of Mecrisp-Stellaris complete with Words such as the disassembler for some MCU's. These files ( where built) can be found in in a "PRECOMPILED" sub directory of your device.

At this time of writing the Thumbulator emulates the following devices for mecrisp-stellaris-2.4.7.

=================== ===
Device
=================== ===
aducm4050
lm4f120-tm4c1294
numworks
stm32f051
stm32f103
stm32f303
stm32l053
=================== ===

.. _run-thumbulator:

Run Mecrisp-Stellaris-stm32f051-RA on your PC!
----------------------------------------------
If you have Linux, you can actually run Mecrisp-Stellaris on it right now, without any hardware at all using Thumbulator. Your choice is limited to the above Devices but it's a easy way to check Forth out. There are virtually no peripherals, one uart port for TX only (prints the character to the console). A port that prints the 32 bit value written to the console, and a port to halt the processor.

I make use of Thumbulator when I need to test different versions of Mecrisp-Stellaris such as :ref:`compare Inlining between the the RA and the Classic Core<inlining>` for this Documentation Site.

How to:
^^^^^^^
I've used a stm32f051-RA kernel but you can easily change to any in the list above.

.. note:: FreeBSD and OpenBSD users may have to change a few paths etc and install Bash then symlink it to /bin/bash.

Basically you just download the latest Mecris-Stellaris Release (I've used a old release here) and perform the following:

=========== ======================================================================================================================================
Action      Command
=========== ======================================================================================================================================
Uncompress  mecrisp-stellaris-2.4.7
cd          /mecrisp-stellaris-2.4.7
execute     release
execute     thumbulator/runcore  thumbulator/thumbulator-stm32f051 stm32f051-ra/precompiled/mecrisp-stellaris-stm32f051-with-disassembler-m0.bin
=========== ======================================================================================================================================

After the last command you should see:
::

 Mecrisp-Stellaris RA 2.4.7 with M0 core for STM32F051 by Matthias Koch

.. warning:: If anything is wrong with your paths or syntax etc, you will get a CORE file in the directory. This is nothing to worry about, just delete the CORE and check the syntax and paths to find the error.

As mecrisp-stellaris-stm32f051-with-disassembler-m0.bin has the dissasembler installed you can create a Word and see the contents in assembly.
::

 : 3plus  3 + ;  ok.

 see 3plus 

 20000398: 3603  adds r6 #3
 2000039A: 4770  bx lr
 
 ok.