nimblemachines / muforth

A simple, indirect-threaded Forth, written in C; for target compiling; runs on Linux, BSD, OSX, and Cygwin

What is muforth?

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.

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.

Under active development

• 8051
• ARMv6-m (aka Cortex-M0/M0+)
• ARMv7-m (aka Cortex-M3/M4)
• MSP430 (TI)
• RISC-V (initially, the SiFive FE310 and GigaDevice GD32VF103)

Dormant, or less actively developed

• ARMv5 (originally targeting an ARM AEB-1 board running an ARM7DI processor)
• AVR (Atmel)
• HC08 and HCS08 (Motorola/Freescale/NXP)
• PIC18 (Microchip)

Tethered vs self-hosted

Unlike a "self-hosted" Forth, where the target contains the dictionary, the text interpreter, and all the tools necessary for assembling and compiling code, muforth supports a tethered development model. muforth runs on the host machine, compiling code and data that are later copied to the target machine and executed there.

Because the dictionary and all the compilation tools reside on the host, only the compiled code and data reside on the target. This makes it possible to target very small devices that only have a few kilobytes of flash and a few hundred bytes of RAM. In contrast, a self-hosted Forth often needs 16 KiB (or more) of flash to be useful, and consumes RAM for the text interpreter and compiler.

The host machine is also orders of magnitude faster than the target, so doing the compilation on the host is essentially instantaneous.

Why yet another Forth?

I initially wrote muforth because I wanted to try out some implementation ideas. The core language primitives are written in C, but initially muforth compiled Forth words via a simple native code compiler for the x86. I quickly realized that simplicity and portability were more important than speed. The current implementation is a straightforward indirect-threaded Forth - and it is quite fast!

Its implementation is no longer the point. Its sole reason for existing is to be a cross-compiler for other Forths, and their implementations are in no way tied to muforth’s. In fact, muforth can be used to compile any sort of code onto the target. I've used it very successfully as a smart assembler for writing AVR and S08 code.

By keeping it small and simple, it is much more likely to be a useful tool that people can customize.

It’s BSD licensed, so do what you want with it! I’d love to hear about innovative or unusual uses of muforth.

Starting points

BUILDING will tell you how to build muforth. It’s very simple.

Look in mu/target/ to find a target that interests you. There is generally a mu/target/<target-name>/build.mu4 that loads the cross-build environment. Use it as an “index” to find the assembler, disassembler, meta-compiler, kernel, and other key pieces of code.

Documentation

Sadly, there isn’t a lot of documentation right now. A good place to start is to read the source.

The code – both the C code that implements the Forth virtual machine and the muforth code that does everything else – is carefully and in some cases extensively (even obsessively!) commented. Right now your best source of documentation is the code! Luckily for you, there isn’t that much of it, so reading it is actually possible. That’s part of the point of muforth; I want it to be a convivial tool.

The heart of the system is the Forth code that muforth reads when it first starts: mu/startup.mu4. You’ll learn a lot by reading this!

muforth.dev will eventually host the muforth documentation. At the moment, it is a collection of journals, essays, and “getting started” pages.

Talks

In March 2008 I gave a talk about bootstrapping, muforth, and convivial tools.

Warning: I wave my arms around a lot, and the audio and video quality isn’t that great, but you might find it interesting, or at least amusing.

It’s also hard to see my slides. If you want to “follow along”, download my slides, and use less to view them – ideally in a text window that is at least 30 lines high – like so:

less -30 ~/muforth/talks/2008-mar-30-PNCA

Above all, enjoy!

muforth's Issues

chipdef files state that it's contents are extracted from the datasheets, but the scripts used to do so seem to be missing

Hi,
the chidefs.lua files all state, that the data got extracted with lua, but the actual scripts aren't there and there is no comment on where to find them.

Including at least a reference would make it way easier to create chipdefs, for new controllers.

Raspberry Pi Pico -- bsd fail

As expected, usb issues w/ new target and BSD (OpenBSD) ...

./muforth -f target/ARM/debug/picoboot.mu4
target/ARM/debug/picoboot.mu4, line 22: usb-write isn't defined

Update Getting started with RISC-V

The instructions for using muforth in Getting started with RISC-V are out of date. The use of openocd is no longer required.

To chat with a target (we'll use the HiFive1 as an example,) use the relevant patched code referenced here until the changes get incorporated into origin/master.

NB: This patch did not add this code, it simply fixes some malfeasance that crept in with changes to asm{{ & }}.

NB: Make sure muforth/mu/serial-target is symlinked to the correct /dev/whateva! On OpenBSD, this is /dev/cuaU1. Make sure you are a member of the group for that device! On OpenBSD, this is group dialer.

cd muforth/mu
./muforth -f target/RISC-V/board/hifive1.mu4
chat

and you should be good to go.

Serial timeout too short for long running interactive code

.5 sec value in muforth/tty.c is too short for testing longish loops; changing value in tty.c to something like 10 sec works until issue can be resolved.

Procedure for unwedging an STM32F0-Discovery board

Bad Flash Happens

Sometimes Things Go Wrong and you find you have a dev board in a state where you can't do anything with flash, which is now mysteriously filled with Really Weird Shit. Today's procedure covers the very recent unwedging of an STM32F051-Discovery board. Don't ask us how it happened, this board showed up in this state.

You have to sidechannel via the serial bootloader

Normal jtagging via muforth/stlink is not going to work. You have to use the serial bootloader. In the example below, we're using a PL2303, but this will work with an FTDI-2232H etc. You just need something that will do serial that has TX, RX, GND and 3.3V.

1. Put female-female jumper wires on the following pins of the PL2303: RXD, TXD, GND, 3.3V

2. Jumper BOOT0 and VDD on the F051 board with a wire or one of those nifty jumper pins pirated off one of your other boards.

3. Attach the PL2303 to the F051 board as follows:

PL2303           F051
TXD      --->    PA10/RX
RXD      --->    PA9/TX
3.3V     --->    3.3V
GND      --->    GND

... and plug it into a usb port.

4. When you build muforth on Linux, it automagically decides muforth/mu/serial-target should symlink to /dev/ttyS0. This needs
   to change because it's a nervy assumption. In this case, the PL2303 will enumerate as /dev/ttyUSB0. Let's get things set up.

$ cd muforth/mu
$ rm serial-target
$ ln -s /dev/ttyUSB0 serial-target

One more "gotcha" --- not all systems have the same idea about which device belongs to which group. Archlinux, for example, decided that this /dev/ttyUSB0 belonged to group uucp, so if you're not a member, you need to add yourself to that group, logout and log back in.

$ sudo usermod -aG uucp $USER

5. Ok, we're logged back in, we're plugged in, and the board is wired per above. Let's do some triage.

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

---- loading messages scroll by ----

(( STM32 serial bootloader support )) <--- This is important
(( ST-LINK debug No supported USB devices found ))  <--- Ignore this, it's spurious noise

boot

Bootloader Version 3.1           <---
Using extended erase command.       | <---------- You want to see this after typing boot
 Ok (chatting) (hex) (flash)     <---

@flash t.erase
NOW HIT THE BLACK RESET BUTTON ON THE BOARD

boot

Bootloader Version 3.1
Using extended erase command.
 Ok (chatting) (hex) (flash)

@flash du

.... and you should see all ffffff's

Groovy. Unplug and reconnect with the board with a normal command string:

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

jtag

ST-LINK/V2 JTAG V15
DFU mode => Mass mode => Debug Mode
      SP             RP              IP
ffffffe0  00000000  00000000*
WARNING: Target's flash image differs from host's. Run flash-image? Ok (chatting) (hex) (flash)

flash-image

erase page   800_0000
program      800_0000 200
program      800_0200 200
erase page   800_0400
program      800_0400 1b8 (Ok) (chatting) (hex) (flash)

verify   Ok  (chatting) (hex) (flash)
PRESS THE BLACK RESET KEY ON THE BOARD

jtag

ST-LINK/V2 JTAG V15
Debug Mode
           SP             RP              IP
20001efc  00000000  00000000*   Ok (chatting) (hex) (flash)

@flash du  should show, starting from address 08000000, an address in ram (20002000) followed by a bunch of 
addresses in 08000000 land

... and that's it, you should be good to go. ;)

Basic clock support available for stm32f407g-discovery board ...

cf: abea06c

target/ARM/stm32/f407_g-example.mu4
and
target/ARM/board/stm32f4-discovery.mu4

Inconsistencies in new decompile code between different targets

Inconsistencies noted in expected output between different targets. Pico and stmf303 appear similar, stmf407g is ... curious. There are likely other targets affected ..

try several serial devices, in sequence, at runtime?

The support for serial targets can be confusing and frustrating. Currently muforth connects to the device specified by a symbolic link - mu/serial-target. One issue with this is that when using USB-to-serial converters (ftdi, pl2303, etc) if the device gets wedged it will often re-enumerate and come up as a different device. Eg, muforth is connected to /dev/ttyUSB0, which wedges and re-enumerates as ttyUSB1. Now you quit muforth and re-run it, and you can't connect. It's ugly and awkward.

However, sometimes - like when using the *-peer code to test a serial protocol, you want muforth to honor the serial-target symlink (which in that case will point to /dev/pty/). Though even in this case re-enumeration (on the peer side) can occur and be confusing.

Probably the best solution is for serial-target to somehow be a template or prefix, and at runtime, muforth tries several variations (at least two: 0 and 1) before giving up.

Sadly, for this work, the exception code has to change, so that the serial interface code can "catch" thrown exceptions, rather than having them totally unwind the stack.

Raspberry Pi Pico -- BSD chat hangs while attempting to connect with target

... and no useful output is available to the user (due to failure of picoboot.mu4 to finish building we don't have spy or bug)

./muforth -d testing -f target/ARM/board/raspberry-pi-pico.mu4 
muforth/64 (60d83f19) 2021-nov-13 16:51
(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.

(( Raspberry Pi Pico board
(( RP2040 chip
(( RP2040 equates ))
(( ARM Cortex-M0+ processor
(( ARM Cortex-M core equates (v6-M and v7-M) ))
(( 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 4# again.  00r again.  i8 again.  sh-imm
again.  ))
(( ARM v6-M meta-compiler (main) ; again.  ))
(( ARM v6-M interaction dumps again.  ))
(( Flash programming save-image again.  ))))))
(( Rasberry Pi PICOBOOT support ))
(( ARM v6-M Forth kernel (ITC) ))))
pico  <---- HANGS HERE

Empty File Loading Issue

Loading an empty file produces the following issue:

touch doug.mu4
./muforth -f target/HC08/doug.mu4

---- snip ------

target/HC08/doug.mu4, line 14 : target/HC08/doug.mu4 Invalid argument
target/HC08/doug.mu4, line 14 : target/HC08/doug.mu4 Bad file descriptor

change __forth to __host

I think __meta for "meta" mode and __host for "host mode" make more sense.

Tag Commits That Require Rebuild?

What do you think about including a boilerplate note/tag that shows up at start of git log for those commits which require a rebuild w/ ./configure.sh && make? Thinking it might be a little opaque for peeps who aren't familiar w/ muforth or muforth -> target relationship ...

Longan Nano and DFU Flashing

Per commit a075094 we appear to have joy with DFU flashing of the Longan Nano using a USB-C cable (as opposed to the serial pins):

sid@vicious:~/muap/mu$ ./muforth -d bootloader -f target/RISC-V/board/longan-nano.mu4 -f target/RISC-V/load-chat.mu4 
muforth/64 (48ef1d57) 2021-dec-15 07:33 (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.

(( Sipeed Longan Nano board 
(( GigaDevice GD32VF103CBT6 chip 
(( GigaDevice GD32VF103xB equates ))
(( Target endianness ))
(( Meta-compiler (chains and token consumers) ))
(( RISC-V memory image ))
(( RISC-V RV32 assembler (I subset) ))
(( RISC-V RV32 assembler (C subset) ))
(( RISC-V RV32 disassembler (I subset) ))
(( RISC-V RV32 disassembler (C subset) ))
(( RISC-V meta-compiler (main) ; again.  ))
(( RISC-V interaction dumps again.  ))
(( Flash programming ))))
(( Serial expect/send ))
(( STM32 serial bootloader support ))
(( STM32 USB DFU support ms again.  >cmd again.  erase-page again.  setup-chunk again.  ))
(( RISC-V serial chat protocol (host) ?spkt again.  >b again.  b> again.  ))))
(( RISC-V serial chat protocol (core) ))
dfu 
WARNING: Target's flash image differs from host's. Run flash-image? Ok (chatting) (hex)
flash-image 
erase   800_0000 
program 800_0000 36c  Ok (chatting) (hex)
verify  Ok (chatting) (hex)

However there appears to be an issue reconnecting with the target over USB. The procedure given in commit message a76d402

• Omits mentioning that dfu should be substituted for boot when flashing via that method

     ./muforth -d bootloader -f target/RISC-V/board/longan-nano.mu4 \
            -f target/RISC-V/load-chat.mu4
       boot        
       flash-image
       verify
       ^C

• and further gives a procedure for reconnecting to the target and verifying the flash procedure ...

    You should now reset the board (by pressing the reset button), re-connect,
    and verify that everything worked:
    
      ./muforth -f target/RISC-V/board/longan-nano.mu4 \
            -f target/RISC-V/load-chat.mu4
      chat
      verify

... but this reconnect procedure fails and the observed behavior on ChromeOS, Archlinux and OpenBSD is that while attempting to chat with the target via USB-C cable:

• The target fails to enumerate on the host without first holding down reset, pressing boot, releasing reset and releasing boot

• Fails to chat with the target and verify ...

sid@vicious:~/muap/mu$ ./muforth -f target/RISC-V/board/longan-nano.mu4 -f target/RISC-V/load-chat.mu4 
muforth/64 (48ef1d57) 2021-dec-15 07:33 (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.

(( Sipeed Longan Nano board 
(( GigaDevice GD32VF103CBT6 chip 
(( GigaDevice GD32VF103xB equates ))
(( Target endianness ))
(( Meta-compiler (chains and token consumers) ))
(( RISC-V memory image ))
(( RISC-V RV32 assembler (I subset) ))
(( RISC-V RV32 assembler (C subset) ))
(( RISC-V RV32 disassembler (I subset) ))
(( RISC-V RV32 disassembler (C subset) ))
(( RISC-V meta-compiler (main) ; again.  ))
(( RISC-V interaction dumps again.  ))
(( Flash programming ))))
(( Serial expect/send ))
(( RISC-V serial chat protocol (host) ))))
(( RISC-V serial chat protocol (core) ))
chat 
chat No such file or directory

• ... unless the -d bootloader switch is included and dfu is executed:

sid@vicious:~/muap/mu$ ./muforth -d bootloader -f target/RISC-V/board/longan-nano.mu4 -f target/RISC-V/load-chat.mu4 
muforth/64 (48ef1d57) 2021-dec-15 07:33 (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.

(( Sipeed Longan Nano board 
(( GigaDevice GD32VF103CBT6 chip 
(( GigaDevice GD32VF103xB equates ))
(( Target endianness ))
(( Meta-compiler (chains and token consumers) ))
(( RISC-V memory image ))
(( RISC-V RV32 assembler (I subset) ))
(( RISC-V RV32 assembler (C subset) ))
(( RISC-V RV32 disassembler (I subset) ))
(( RISC-V RV32 disassembler (C subset) ))
(( RISC-V meta-compiler (main) ; again.  ))
(( RISC-V interaction dumps again.  ))
(( Flash programming ))))
(( Serial expect/send ))
(( STM32 serial bootloader support ))
(( STM32 USB DFU support ms again.  >cmd again.  erase-page again.  setup-chunk again.  ))
(( RISC-V serial chat protocol (host) ?spkt again.  >b again.  b> again.  ))))
(( RISC-V serial chat protocol (core) ))
dfu  Ok (chatting) (hex)
verify  Ok (chatting) (hex)

But ... Serial Joy (PL2303)

However, if we connect to the target via the serial pins (in this case with a PL2303) we note that everything Just Works post DFU flash:

sid@vicious:~/muap/mu$ ./muforth -f target/RISC-V/board/longan-nano.mu4 -f target/RISC-V/load-chat.mu4 
muforth/64 (48ef1d57) 2021-dec-15 07:33 (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.

(( Sipeed Longan Nano board 
(( GigaDevice GD32VF103CBT6 chip 
(( GigaDevice GD32VF103xB equates ))
(( Target endianness ))
(( Meta-compiler (chains and token consumers) ))
(( RISC-V memory image ))
(( RISC-V RV32 assembler (I subset) ))
(( RISC-V RV32 assembler (C subset) ))
(( RISC-V RV32 disassembler (I subset) ))
(( RISC-V RV32 disassembler (C subset) ))
(( RISC-V meta-compiler (main) ; again.  ))
(( RISC-V interaction dumps again.  ))
(( Flash programming ))))
(( Serial expect/send ))
(( RISC-V serial chat protocol (host) ))))
(( RISC-V serial chat protocol (core) ))
chat 
Chat firmware version 48ef1d57 Ok (chatting) (hex)
verify  Ok (chatting) (hex)

Documentation: Make explicit the consequences of flashing the target

Either through a message via load file or by providing a test mechanism immediately after initiating chat, make explicit to the user that if they flash the target with a certain set of code they must always initiate chat with the target using that code.

If you don't and (for example) you go fetch a register and get a stack full of goofy values, it's prudent to run

verify

If you get just an Ok back, then something else is up, but if you get a spew of crazy numbers followed by an ok then you need to either flash with your current code or reload using the code you originally flashed with. Pro-tip: keep a diary. ;)

Maybe just default to automagically running verify after jtag? We need something, as this is going to be another brittle point for new users.

-d boot: commit message inadequately and inaccurately describes use

commit 156025b

STM32F407g

Johnny reads this:

- -d boot  instead of  -d bootloader
- board files do not need to load DFU; if boot is defined, both the
  serial and DFU bootloader code is loaded

Johnny tries this:

johnny@rotten:~/moocow/mu$ muforth -d boot -f target/ARM/board/stm32f4-factory-discovery.mu4 
muforth/64 (fa85db57) 2021-dec-07 21:02 (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.

 ( STM32F4 Discovery board
(( STM32F407xG chip 
(( STM32F407xx equates ))
(( ARM Cortex-M4 processor 
(( ARM Cortex-M core equates (v6-M and v7-M) ))
(( Target endianness ))
(( Meta-compiler (chains and token consumers) ))
(( ARM v6-M memory image ))
(( Reading Motorola S-record (S19) files ))
(( ARM v6-M Thumb2 disassembler ))
(( ARM v7-M Thumb2 disassembler L@ again.  ))
(( ARM v6-M Thumb2 assembler 4# again.  00r again.  i8 again.  sh-imm again.  ))
(( ARM v7-M Thumb2 assembler ))
(( ARM Cortex-M3/M4 bit banding support )
(( ARM v6-M meta-compiler (main) ; again.  ))
(( ARM v6-M interaction dumps again.  ))
(( Flash programming ))
(( Serial expect/send ))
(( STM32 serial bootloader support 
target/ARM/debug/stm32-bootloader.mu4, line 52: /page isn't defined

STM32F051

Queenie says "Let me try the F051, Johnny!"

queen@carlotta:~/moocow/mu$ muforth -d boot -f target/ARM/board/stm32f0-factory-discovery.mu4 
muforth/64 (fa85db57) 2021-dec-08 06:46 (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 
(( STM32F051x8 equates ))
(( ARM Cortex-M0 processor 
(( ARM Cortex-M core equates (v6-M and v7-M) ))
(( Target endianness ))
(( 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 4# again.  00r again.  i8 again.  sh-imm again.  ))
(( ARM v6-M meta-compiler (main) ; again.  ))
(( ARM v6-M interaction dumps again.  ))
(( Flash programming ))
(( Serial expect/send ))
(( STM32 serial bootloader support boot again.  ))
(( STM32 USB DFU support No supported USB devices found. ))))))
(( ST-LINK debug ST-LINK/V2 >b again.  b> again.  h* again.  spy again.  
(( STM32 flash programming code ))))
(( STM32F051x8 example startup code 
(( ARM v6-M Forth kernel (ITC) regs>mask again.  dpop2 again.  dpop3 again.  rpush2 again.  rpop2 again.  ))))))
boot 
boot No such file or directory

Queenie and Johnny make ..

Frothy Spittle Noises

This appears to be too brittle; it might work for the F303 but it isn't working for the above; all relevant files this end have been hand massaged (but not pushed to public yet) to reflect updates/changes to the F303 board files etc. ... which again brings up the oft discussed point that this whole loader process is fragile, convoluted and a bit of a hot mess atmo. The chip id could be yanked in as part of the boot process and then the appropriate files loaded automagically for starters ...

New HiFive chat flash process fails

frisky@bits:~/muap/mu$ muforth -f target/RISC-V/board/hifive1.mu4 -f target/RISC-V/load-chat.mu4 
muforth/64 (f1cbc681) 2021-dec-08 06:46 (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.

(( SiFive Hifive1 board 
(( Chip equates for SiFive FE310-G000 
(( Target endianness ))
(( Meta-compiler (chains and token consumers) ))
(( RISC-V memory image ))
(( RISC-V RV32 assembler (I subset) ))
(( RISC-V RV32 assembler (C subset) ))
(( RISC-V RV32 disassembler (I subset) ))
(( RISC-V RV32 disassembler (C subset) ))
(( RISC-V meta-compiler (main) ; again.  ))
(( RISC-V interaction dumps again.  ))))
(( Serial expect/send ))
(( RISC-V serial chat protocol (host) ))))
(( RISC-V serial chat protocol (core) ))
(( RISC-V Forth kernel push1 again.  push2 again.  pop1 again.  pop2 again.  rpush1 again.  rpush2 again.  rpop1 again.  rpop2 again.  ))
(( HiFive1 SPI flash experiments ))
(( HiFive1 SPI flash support ))
chat 
Chat firmware version f1cbc681
      IX        SP        RP        IP
00000000  80003f0c  00000000  00000000*  Ok (chatting) (hex)
verify 
verify <key timed out

NB: Led flash sequence shows new code has been flashed ...

Adventure Time: Create Build Option To Use Cosmopolitan libc

I remember reading Justine's post about this a year and change ago and thinking, hmmm, this is extremely interesting ... and then she popped up on r/Forth today and suggested using Cosmo to build for Windows ... which really needs some love.

I'm proposing we chat about creating a build option to use Cosmopolitan and see what comes out the other side.

bsd-usb-support branch missing files

bsd-usb-support branch is missing target/ARM/board/pico files

target/RISC-V/asm-rv32i.mu4: mismatched stack comments?

------ snip -----

(line)
350      ( Compare two registers: ( rs1 rs2 - op)
351      11_000_11  000  SB-cond !=   ( beq)
352      11_000_11  001  SB-cond =    ( bne)
353      11_000_11  100  SB-cond >=   ( blt)
354      11_000_11  101  SB-cond <    ( bge)
355      11_000_11  110  SB-cond u>=  ( bltu)
356      11_000_11  111  SB-cond u<   ( bgeu)

------ snip ------

target/ARM/v6-m/kernel-itc.mu4 leaves user in region flash

...hence colon definitions will not work on ARM targets OOTB. User should verify they are in ram by executing the word ram or adding it to their loader file until this is fixed. User can check whether they are in flash or ram by executing the word region and noting the address left on the stack.

Raspberry Pi Pico seg faults and dumps core

... if attempt is made to dump flash from >= 1000_0000. This is because flash interface is not set up yet. Once the flash interface is set up we can close this issue.

FRDM-KL25z fails loading ...

(( Freescale FRDM-KL25Z board
(( KL25Z128 chip
(( ARM Cortex-M0+ processor
(( ARM Cortex-M core equates (v6-M and v7-M)
target/ARM/v6-m/core-equates.mu4, line 15: vector isn't defined

Download

Pico: Definition of ack>/ack< missing after latest commit

commit 33394be removed the definition of ack>/ack< from target/ARM/debug/picoboot.mu4

Until fixed, patch by hand, insert below definition of pico>

( Transferring data)
: ack> pad 0 uread ;
: ack< pad 0 uwrite;

st demo code STM32F4-Discovery board causes breakage

... with loop execution when chatting w/ target (kernel-itc loaded into ram.)

This is due to the watchdog timer being set.

Example of issue

cd ~/muforth/mu
./muforth -f target/ARM/board/stm32f4-discover.mu4 ram -f target/ARM/v6-m/kernel-itc.mu4
jtag
ram
hex
: w 0 do loop ;
100000 w    <--- hangs, chat lost with target

Workaround

Wipe out the factory vector table. The following also sets GPIOD up so you can "do your own thang with der Blinken lights."

First, save the factory flash image just in case you later decide you had an emotional attachment to it or for later study:

cd ~/muforth/mu
./muforth -f target/ARM/board/stm32f4-discovery.mu4
@flash 4590 read-image
save-image fileName.img

...this will automagically save fileName.img in ~/muforth/mu/

Next, replug the board and run the following:

cd ~/muforth/mu
./muforth -f target/ARM/board/stm32f4-discovery.mu4 ram -f target/ARM/v6-m/kernel-itc.mu4
jtag
ram
hex
0 t.erase
ff RCC_AHB1ENR !
55000000 GPIOD_MODER !

You can create a custom loader file anywhere you like to handle initiating chat with the target and getting it set up to do something useful with the GPIO's. Canonically the assumption is made that you would create it in muforth/mu, but then canonically the assumption is made that you would work inside ~/muforth/mu and type ./muforth everytime you wanted to fire it up. Some of us like to just have a bin/ directory in $HOME and symlink muforth from there so we can just type 'muforth' and be on our merry way from wherever the hell we are. It's your sandbox, do as thou wilt. In the following example, we will use the canonical assumptions because it's canon, damn it.

loader.mu4

ld ~/muforth/mu/target/ARM/board/stm32f4-discovery.mu4
ram
ld ~/muforth/mu/target/ARM/v6-m/kernel-itc.mu4
jtag
ram
hex
ff RCC_AHB1ENR !
55000000 GPIOD_MODER !

If you want all the GPIO's configured as outputs OOTB, then just change 55000000 to 55555555.

To load:

cd ~/muforth/mu/
./muforth -f loader.mu4

Add udev rule for Silicon Labs CP210x UART Bridge

Need this for ESP8266 NODEMCU/AI-Thinker boards

NixOS, RISC-V, openocd and muforth

This is the fastest way to start chatting with the HiFive1 using
muforth/openocd on NixOS. Currently, this has only been tested with
NixOS version 17.03 running 4.9.20-grsec kernel.

Step 1. Git muforth.

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

Pay particular attention to the message produced after running muforth/src/configure.sh. Make sure
you append udev.nix to /etc/nixos/configuration.nix.

Step 2. Download the appropriate openocd binary per instructions here:

http://muforth.nimblemachines.com/getting-started-with-risc-v/

Step 3. Make certain that you have both patchelf and libusb-1.0x. If
you're running NixOS I'm assuming you know how to get them if you don't
have them. ;)

Step 4. Since you built muforth from source, you can use patchelf to find out
where your interpreter is located:

$ patchelf --print-interpreter muforth/mu/muforth 

Point your openocd binary at that terrifying output with patchelf.

$ patchelf --set-interpreter /nix/store/<long hairy string unique to
your system>-glibc-2.25/lib/ld-linux-x86-64.so.2 ./openocd/bin/openocd

NB: The above assumes you did the logical thing and untarred that
openocd binary archive into your home directory without naming it
anything cute or clever.

Step 5. You'll need to set your LD_LIBRARY_PATH to point at the location in
/nix/store of the user-environment/lib that contains your libusb* files.
You can use the path of inconvenience and type it manually every login
session or once you figure out where it is, include it in a script. This
is the path of least resistance. I recommend that path. (Binaries and
LD_LIBRARY_PATH cause intermittent grief in NixOS land, so it would be
wise to remember this workaround. It would also be wise to not set
this permanently, as more permanent workarounds to LD_LIBRARY_PATH
issues have been known to cause wailing and gnashing of teeth.)

$ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/nix/store/<long hairy string
peculiar to your environment>-user-environment/lib

Remember the Path of Least Resistance: you'll put that in a shell script
and run it once per login session.

Step 6. Ready, set, chat with target. In one terminal window:

$ cd muforth/mu
$ target/RISC-V/start-openocd.sh (remember to modify this per the
   instructions at http://muforth.nimblemachines.com/getting-started-with-risc-v/)

In another terminal window:

$ ./muforth -f target/RISC-V/build.mu4
$ jtag

"You should see a dump of four registers, all zero except for SP."

-- @0x0dada

Thank You

Not an issue - just a thank you for such an excellent artefact!

I've recently been converted to Forth - it really is an excellent language - and have been looking for a decent implementation that will run nicely on the 64 bit mac. I'm really pleased with this! Thanks Again!!

Heads up: label definitions on HiFive1 currently broken + eabi use

label definitions are currently broken on the HiFive1

A patch is currently in the pipeline, but if you're banging away at the HiFive1 and trying to figure out why label defs are giving you extremely curious results, it's because label is currently broken.

You can use code words, however:

   code s3@ top push1 s3 top mv next ;c
   code s3! top s3 mv top pop1 next ;c

riscv-eabi-spec support will be dropped for now

Also, presently muforth uses the riscv-eabi-spec but after discussion today it's going to be dropped until that actually gets ratified.

Many target/ARM/board files leave the user in an inconsistent state wrt flash

If a fresh factory board is loaded with one of the "new" files with the "special" example code, the unwary or new user is going to note some inconsistencies and exciting behavior wrt to working with flash.

See #29, #31 and ac2544d

#################################################
Fri Nov 19 06:46:45 PST 2021
OpenBSD 7.0
GENERIC.MP#296 i386
#################################################

The anomalous output for the f0 can be explained by the fact that the
master public repository (https://github.com/nimblemachines/muforth.git)
is loading "special" example code:

stm32f0-discovery.mu4

loading STM32F0 Discovery board

ld! target/ARM/stm32/f051_8.mu4
ld target/ARM/debug/stlink-v2.mu4

flash
ld target/ARM/stm32/f051_8-example.mu4 <-----  RUH ROH

This is guaranteed to create a tripping point for new users.  If that's
you and you're trying to figure out whacky behavior with flash, you can
save your factory image (cf issues #18 Workaround and #31 on main repo
above) and reflash with this loaded code.

This needs to be changed; it violates the principal of least
astonishment and given the current haphazard state of muforth
documentation in general and target documentation in specific, we need
to do the least astonishing thing.

It is easily rectified by having two board files; one which a new user
can use with the factory demo code and one which loads the special
example code and a nice note in target/ARM/board which clearly explains
the difference.

As we can see below, reflashing with the default special code takes care of the decompile inconsistencies wrt
the stm32f051:

ST-LINK/V2 JTAG v15 
DFU mode => Mass mode => Debug mode 
      SP        RP        IP
20001fe8  00000000  00000000*  Ok (chatting) (hex) (flash)
00 t.erase  Ok (chatting) (hex) (flash)
jtag 
ST-LINK/V2 JTAG v15 
Debug mode 
      SP        RP        IP
20001f84  00000000  00000000*  Ok (chatting) (hex) (flash)
flash-image 
erase page 800_0000 
program    800_0000 200 
program    800_0200 200 
erase page 800_0400 
program    800_0400 1b8  Ok (chatting) (hex) (flash)
verify  Ok (chatting) (hex) (flash)
' flash-leds dec 
08000544  : flash-leds 
08000548  080000f0 (lit) 
0800054c  00000300 
08000550  080000f0 (lit) 
08000554  48000814 GPIOC_ODR 
08000558  08000324 ! 
0800055c  080000f0 (lit) 
08000560  00020000 
08000564  08000528 wait 
08000568  080003d4 0 
0800056c  080000f0 (lit) 
08000570  48000814 GPIOC_ODR 
08000574  08000324 ! 
08000578  080000e0 (unnest) 
0800057c  080003dc 1 
08000580  080000f0 (lit) 

Improper setting or omission of flash latency value of FLASH_ACR for STM32F407G

Help Help, My Flash Is Wedged!

An improper setting of or omitting to set FLASH_ACR on the STM32F407G-discovery board will cause flash to become locked and the user will be unable to read or write to the flash, including reflashing the chip without the following procedure.

It is critical to match the FLASH_ACR value with the voltage correctly. cf: ST Reference Manual RM0900, en.DM00031020.pdf pages 80-112 for description. Basically, if you do not, on the next attempted use of flash ST's boot ROM code will lock the flash and you will be unable to read or write to it.

Procedure for Resetting

1. With the board unpowered, jumper between the BOOT0 and VDD pins.

2. Enter the following sequence carefully. Example shows flashing the chip with the factory demo code covered in the workaround in #18.

$ cd muforth/mu

$ ./muforth -f target/ARM/board/stm32f4-discovery.mu4 ram -f target/ARM/v6-m/kernel-itc.mu4 load-image stm32f407.img

    jtag
    00 RCC_CFGR !
    00 t.erase
    jtag
    flash-image
    verify

3. Re-power the board and reconnect, everything should be working.

OpenBSD: Inclusion of -DDEBUG_STACK in src/Makefile.in results in error

On OpenBSD 7.0 --current GENERIC.MP i386, inclusion of -DDEBUG_STACK in src/Makefile.in results in an undeclared
identifier error:

cc -O2 -Wall -fomit-frame-pointer -Wno-int-to-pointer-cast
-DDEBUG_STACK -DDEBUG_USB_ENUMERATION  -c kernel.c
cc -O2 -Wall -fomit-frame-pointer -Wno-int-to-pointer-cast
-DDEBUG_STACK -DDEBUG_USB_ENUMERATION  -c engine-itc.c
cc -O2 -Wall -fomit-frame-pointer -Wno-int-to-pointer-cast
-DDEBUG_STACK -DDEBUG_USB_ENUMERATION  -c interpret.c
interpret.c:232:38: error: use of undeclared identifier 'uval'
        fprintf(stderr, "  %16llx", (uval)SP[3-i]);
                                                     ^
1 error generated.
*** Error 1 in ~/muforth/src (<sys.mk>:87 'interpret.o')

This error will impact other systems/architectures as well. (Tested and present Archlinux/AMD64 and aarch64, Termux aarch64)

RISC-V: meta isn't defined

This again, and it impacts the two current boards, hifive1 and Longan Nano

All platforms

ChromeOS (chromebook) devices may need to change chunk size in chat-host.mu4

This isn't a muforth bug, but rather a ChromeOS issue. See this README.

Input text is currently treated as a stream of bytes ...

... any bytes ... this should be changed per recent chat. 7 bit ASCII only ftw.

Feature request/discussion: v6-m/flash.mu4 modification

save-image/read-image in v6-m/flash.mu4 should be renamed save-flash-image/read-flash-image respectively as they are currently (and correctly) tightly coupled to specific notions of where the flash image resides.

Two "new" definitions of save-image and read-image should be crufted together that allow saving an image from a specific address range.

Example: On m4 devices, a mirror copy of flash (8000000) exists starting at address 0. Currently we cannot do the following:

0 4590 read-image
save-image zerocopy.img

serial-terminal.mu4 depends on serial.mu4

Minor tweak suggestion:

Add:

ld target/common/serial.mu4

to serial-terminal.mu4

Thinking that target/common/serial-terminal.mu4 should just load serial.mu4 since successful use of former depends on tty-target which is defined in latter.

Update 99-muforth.rules ...

... to include vendor id for the Raspberry Pi Pico so Linux users can talk to the thing!

In the meantime, if you just can't wait for the devs, append the following to /etc/udev/rules.d/99-muforth.rules

SUBSYSTEMS=="usb", ATTRS{idVendor}=="2e8a", OWNER:="ThatsYOUBaby"

and then

sudo udevadm control --reload