.. index:: hosted-or-tether .. _hosted-or-tether: .. Created hosted-or-tether.rst: Sat 10 Dec 2022 16:23:10 AEDT .. Full Path: /home/tp/mecrisp-unofficial-doc/hosted-or-tether.rst .. Author Copyright 2022 by t.j.porter .. Made by /home/tp/projects/scripts/makerst.sh -->/usr/local/bin/makerst .. license: MIT, please see COPYING Hosted or Tethered ? ==================== Whats the difference between *hosted forths* and *tethered forths* ? This is a *very* complex subject but I'll try and keep this article as simple as I can. .. seealso:: :ref:`Hosted Or Tether Part 2` Hosted ------ The most common Forth is one that is *hosted* because it runs directly on the microcontroller. There are a *LOT* of *hosted* Forths but the examples below are Forths I use or have found interesting Typical Hosted Usage ^^^^^^^^^^^^^^^^^^^^ A binary image is flashed to the target mcu with a interactive Forth REPL providing the developer interface. Program development is performed on the REPL in real-time with the turnkey program running on the same chip. Because of REPL hardware interactivity, problem solution and development is rapid. Examples ^^^^^^^^ ====================================== ================================================ Hosted Forth MCU ====================================== ================================================ Mecrisp-Stellaris ARM Cortex-M Mecrisp Texas Instruments MSP430 Mecrisp-Quintus RISC-V FastForth MSP430 FlashForth PIC, AVR Mega Amforth AVR Mega, MSP430 ====================================== ================================================ Tethered -------- A far less common forth is the *tethered* type. In this case the target microcontroller is controlled remotely by a *HOST* using a 'TETHER' or 'UMBILICAL' cable. The host may be a embedded system or a PC depending on the design of the particular tether. Once development is completed the umbilical is disconnected from the host and the target runs standalone. Mecrisp-Stellaris ^^^^^^^^^^^^^^^^^ Whats to tell ? * Download the Mecrisp-Stellaris release * Flash the premade binary in the release to your target * Connect a terminal and start coding ! .. warning:: Unless you're a Mecris-Stellaris expert already, I recommend reading :ref:`MECRISP-STELLARIS, FIRST STEPS` before you use it. .. seealso:: :ref:`BASIC BEGINNER FIRST STEPS` Typical Usage ^^^^^^^^^^^^^ This varies among different types of tether as listed below. Tethered Examples ^^^^^^^^^^^^^^^^^ ================================ ==================== ====================================== ====================================== ============================================ Name MCU Tether Type Biggest Pro Biggest Con ================================ ==================== ====================================== ====================================== ============================================ Mecrisp-Across (GPL) MSP430 Interactive (Emulation), Compiled Smallest target binary image Emulation is 4x slower than the target Mu-Forth (Open Source) Cortex-M Interactive (Mini Forth Target Kernel) Uses SWD as the tether Needs a lot more documentation MyForth (license ?) 8051 Non-interactive, Compilation, Monitor Uses Gforth as cross-compiler Lack of interactivity, ancient ================================ ==================== ====================================== ====================================== ============================================ Mecrisp-Across -------------- .. image:: pics/f4disco-roundpcb-2.jpg * A PC based SWDCOM user terminal is connected to the Mecrisp-Stellaris host (itself running Mecrisp-Across.fs) via USB running on a STM32F4 Discovery Board. This USB cable also supplies the power. * The MSP430 target (the round board) is connected to the host with a four wire JTAG tether cable which also supplies the power. There are two Modes available at this stage, Emulation and Compilation. Emulation (Development) Mode ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The Forth REPL appears to be on the target MSP430 as registers can be altered and their contents read in real time. However this is an illusion as the actual Forth is hosted on the F4 Discovery board which is controlling the target via JTAG. The target is actually in reset the whole time, meaning the target CPU is off-line and cannot interfere. The drawbacks of this mode are 1. Speed. Emulation is about four (4) times slower than when the final compiled binary is run on the target in standalone (non tether mode). 2. Lack of interrupt capability. Compilation (Standalone Mode) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The host compiles the developed Forth source into a highly optimised binary image which it then flashes to the target non volatile memory in Turnkey configuration. This means the target will now behave exactly as it did in emulation mode, but at four times the speed. There is no Forth on the target now and it cannot be reconnected to the tether as before for further interactive development. To do so requires the Host take control again ignoring the target flash content. A simple 'blinky' program will only require a total of about 60 bytes on the target. .. note:: this stage is almost identical to what you would have if the 'blinky' had been written in C, compiled and flashed to the target. Mecrisp-Across is a very complete and efficient Tethered Forth, which offers the same efficiencies as C, but also includes the interactivity that C lacks. Mu-Forth for the STM32F0 Cortex-M0 ---------------------------------- * The Mu-Forth is run on a Linux PC and a fast, stable Curses REPL with history is provided. * The target, a STM32F0 Discovery board is connected to the PC via a USB tether cable from the SWD interface. This also supplies the power. There is just a single development mode. Development Mode ^^^^^^^^^^^^^^^^ The Forth appears to run on the target and this time it actually is because Mu-Forth flashed a mini Forth kernel (about 1200 bytes) to the target via SWD. This means the PC Forth talks to the target mini Forth over the tether cable. If a blinky program is run, the led will blink while tethered and also blink while untethered. The blink rate will be the same in either mode, i.e. there is no speed difference unlike Mecrisp-Across. Unlike Mecrisp-Across, the target can be reconnected to the host and REPL communications will resume. The penalty for this feature is that the target flash memory size is now about 1500 bytes as it includes the mini-Forth kernel. Summary ^^^^^^^ Mu-Forth is quite complex and badly needs more user documentation. My above doc has barely touched the various parts and there is a lot to learn before one can use it productively. It is however the only cortex-M0 and M3 Tethered Forth I have found to be reliable and easy to use. If you install Mu-Forth, be sure to run "git log" and read everything starting at the beginning, it will be worth your time. .. note:: Mu-Forth supports many more MCU's but this is outside the scope of this short article. .. SEEALSO:: My :ref:`RPI muforth image` READY TO RUN! My-Forth for the 8051 --------------------- MyForth, a Minimalist 8-Bit Forth for 8051 Chips. Written by Charley Shattuck, MyForth is an 8-bit minimalist Forth for 8051 processors. It uses many of the principles and features of ColorForth, including the use of color to highlight source code functionality, efficient tail recursion, two vocabularies and the elimination of the "else" construct in favor of code exits. Because MyForth is hosted by GForth, it can run in both Windows and Linux environments. .. image:: /pics/8051.jpg I have not used My-Forth because I find 8051's are a PITA to flash and I have a zillion STM32F051 in stock. I did however design and release a GPL *BURNER* design for the *AT89C2051* back in 1999, 15 years before I stumbled across STM32 micros. .. image:: pics/burn.jpg To use MyForth you must first install GForth, a mature, free, LPGL Forth that is commonly available on the Internet. Installation is straightforward. MyForth assumes that Gforth is installed to the default directories. Application Development ^^^^^^^^^^^^^^^^^^^^^^^ * Install the MyForth bootloader on the target. Good luck with that, but once it's on, you won't have to do it again. To work with MyForth, every Target chip must have a bootloader programmed into it. * Compile your source with the *C* command. Compiler errors will be flagged by Gforth so at this stage it's much like a C compiler. * Optionally, decompile with the *SEES* command to check the result manually. .. image:: pics/myforth-8051-dis.jpg * Burn the binary to the target 8051 with the *D* command which tells GForth to open the comm. port, download the executable image to the Target, and establish communication with it. * Test by passing parameters to the program residing in the target by putting numbers on the target's stack if/when things aren't working as planned. .. warning:: MyForth does not check for compilation past the end of ROM. It does display the total ROM used at the end of each compilation and the Host stack. You can use these indicators to determine if there is a compilation error needing your attention, such as exceeding available ROM. Tethered Operation ^^^^^^^^^^^^^^^^^^ Passing Parameters ~~~~~~~~~~~~~~~~~~ You can pass parameters to the program residing in the Target by putting numbers on the Target's stack. To do this, just enter the numbers on the command line followed by a # sign. The # is a GForth Word that executes to compile code in the Target's image that will put a byte on the Target's stack when the Target executes the Word. To enter a 16-bit value (e.g., an address), follow the number with ## (also a Target Word). Using these Words following a number is a bit different from most Forth systems that put numbers on the stack without a # or ##. The reason for using these Words after numbers is that it greatly simplifies the compiler and tethered interpreter. It also allows you to specify which stack is being referenced (i.e., Target or GForth). Stack Display ~~~~~~~~~~~~~ As with most Forth systems, you can display the stack contents with .s. Entering .s at MyForth's ok prompt is a convenient way to verify that the Target is responding. Defined Words ~~~~~~~~~~~~~ Display the Words defined on the Target by entering *words" at the *ok* prompt. Summary ^^^^^^^ MyForth does look very interesting and is claimed to work with my Silabs 'Toolstick' boards I purchased in 2014 but are now obsolete. If I every try them, I'll update this 4Jan23 doc. Links ----- * `Mecrisp-* `_ Mecrisp-Stellaris is the younger sister of Mecrisp and runs on various ARM Cortex M chips. This is a big family of microcontrollers with a common processor architecture and very different peripheral capabilities. Despite the name, not only Stellaris chips are supported: It runs on a wide variety of chips of the four core flavours M0, M3, M4 and M7. Mecrisp-Stellaris fits into 16 kb of flash and runs with at least 1 kb of ram. The RA cores contain a much more advanced compiler featuring register allocation and weigh in at 20 kb. If you wish your favourite chip to be in this list, just get in contact, and maybe there will be another port soon. You can also try Mecrisp-Stellaris on Linux and FreeBSD Mecrisp is an implementation of a standalone native code Forth for MSP430 microcontrollers. Many chips and all current MSP430 based Launchpads are supported. It fits into 11 kb of flash or fram and runs with at least 512 bytes of ram. You can choose to compile to flash or to ram, and it generates native code with folding, inlining of short words and it opcodes common instructions. Note that it doesn't need to save any pointers, so it compiles directly into flash memory without the need for erase cycles. It is completely interrupt-save and you can hook your Forth definitions to interrupt vectors. Of course, you should not hook create to a timer interrupt, unless you want all your memory to be filled with random creatures :-) Although it is in spirit of ANS, there are a few differences: Be careful ! * `Mecrisp-Across (my doc site) `_ Mecrisp-Across is a very strong optimising cross compiler running on STM32F4 Discovery, TM4C1294 or ARM Linux and generating code for small classic MSP430 chips like MSP430F2012. It is capable of global optimisations, automatic inlining, dead code elimination and register allocation of both data and return stack across control structures. On TM4C1294 host Mecrisp-Across offers IO port redirection into real hardware for interactive testing before cross compilation * `Mu-Forth `_ 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 – 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. * `FastForth `_ FastForth for MSP430FRxxxx TI's CPUs, light, fast, reliable. Tested on TI MSP-EXP430FR 5739, 5969, 5994, 6989, 4133, 2476, 2355, 2433 launchpads, at 1, 2, 4, 8, 12, 16 MHz plus 20 & 24 MHz with MSP430FR(23xx,57xx) devices. * `Flashforth `_ FlashForth is a Forth stamp system implemented on the Microchip 8-bit PIC18F and 16-bit PIC24, 30, 33 and the Atmel Atmega microcontroller families. FlashForth also works on the popular Arduino UNO and MEGA boards. FF (FlashForth) allows you to write and debug complex real-time applications. The complete system including the compiler is executing on the microcontroller. A Forth interpreter, compiler, assembler, multitasker and user definable interrupts are provided. * `Amforth `_ AmForth is an easily extendible command interpreter for the Atmel AVR8 Atmega micro controller family and some variants of the TI MSP430. The RISC-V CPU (32bit) is currently beeing worked on. It has a turnkey feature for embedded use too. AmForth is published under the GNU Public License v3 (GPL). A commercial use is possible but for traditional commercial uses there are commercial Forths — amForth just is not one of them. AmForth runs completely on the controller. It does not need additional hardware. It makes no restrictions for hardware extensions that can be connected to the controller. The default command prompt is in a serial terminal. The command language is Forth. AmForth implements an almost compatible Forth 2012 indirect threading 16bit Forth. AmForth for the AVR8 needs 8 to 12 KB Flash memory, 80 bytes EEPROM, and 200 bytes RAM for the core system. A similar code for the MSP430 fits into 8KB flash. The MSP430 info flash is used for similar purposes as the EEPROM for the AVR8 platform. The 32-bit variants for ARM and RISC-V are experimental. They share most of the high-level code with the 16-bit variants. * `MyForth `_ Developed by Charley Shattuck, with lots of help from Bob Nash. This version is intended for embedding in small 8051 based projects. The main features of this forth, is the use of macros and macro like instructions to generate 8051 assembler instruction. Using SEE, a forth word or instruciton, it will dissasemble the current code into assembler instructions so you can see if your doing what you wanted to do. Like other embedded forths, you use gforth running on a PC to talk to the project cpu as if you were running a full development platform on your project board. This tethering of the forth to the product is what makes development extrememly fast and efficient. .. seealso:: :ref:`Unusual Forths`