Riscy Pygness – Pygmy Forth for the ARM

Table of Contents

1 News

1.1 December, 2013

Thanks to Jean-Claude Wippler for suggesting an improvement to the first line of riscy.tcl and for changes to the openSerialPort1 procedure in riscy.tcl to allow the serial port to work on a Mac.

He recommends changing the first line of riscy.tcl to the following:

#!/usr/bin/env tclkit 

and here is the updated openSerialPort1 procedure:

proc openSerialPort1 {} {
    global tty1 serialPort1 isUnix1
    # open a serial port to the target
    catch {close $tty1}
    if {$isUnix1} {
        # 'file exists' always returns false on W98, so
        # only run this test on unix
        if {! [file exists $serialPort1]} {
            error "serial port1 $serialPort1 does not exist"
        }
    }
    if {[catch {
        # set tty1 [open $serialPort1 w+]
        #jcw mod 2013-11-30
        set mode RDWR
        if {$::tcl_platform(os) eq "Darwin"} {
          lappend mode NONBLOCK ;# avoid hanging on open
        }
        set tty1 [open $serialPort1 $mode]
        #jcw end
        fconfigure $tty1 -mode $::baudrate,n,8,1 -translation binary -buffering none \
            -blocking 1  -handshake none -timeout $::serialTimeout1
        #jcw mod 2013-11-30
        if {$::tcl_platform(os) eq "Darwin"} {
          # prevent modem ctl from blocking serial ouput
          exec stty clocal <@$tty1
        }
        #jcw end
    }] != 0} {
        error "cannot open serial port1 $serialPort1"
    }
    drain1
    fileevent $tty1 readable [list collectMessage]
}

1.2 November, 2013

It looks like there is a problem with the U/MOD code. Look for the routine that starts something like this in the assembly language:

;;;; label UslashMOD is Forth word U/MOD ( dividend divisor - uR uQ) 
; Divide 32bits by 32bits with 32bit remainder and 32bit quotient.

Thanks to Mark Manning for reporting it and for providing a fix. He says

"I think this is fixed… this now does a 64/32 divide not a zero extended 32 by 32."

and here is his replacement code, however he notes that it still doesn't quite work right.

@ divide 64 bit r1:r2 by 32 bit r0
@ returns quotient on stack and remainder in r0

@      ( ud un --- q r )

CODE "um/mod", ummod
  ldmia sp!, { r1, r2 }
  mov r3, #32
1:
  adds r2, r2, r2
  adc r1, r1, r1
  cmp r1, r0
  addcs r2, r2, #1
  subcs r1, r1, r0
  subs r3, r3, #1
  bne 1b        @ gnu assembler, branch backwards to local 1
  PUSH r1
  mov r0, r2
  NEXT

Please note the stack effect differences.

I plan to write some tests and sort all this out, but it may be a while. Meanwhile, if anyone wants to do it first, have at it and let me know what you come up with. At least, be sure to write tests for your own applications to be sure this doesn't bite you.

I was shocked to see that the previous news item was posted more than 2 years ago. As Willie Nelson might say, Funny How Time Slips Away (http://grooveshark.com/#!/willie_nelson). I've been tied up with my Nepo Press (http://nepotism.net) work. If anyone is interested in publishing eBooks (or printed books), take a look at http://nepotism.net/formatting.

1.3 October, 2011

  • Thanks to Robert Sexton, Riscy Pygness has now been ported to the TI/Luminary Stellaris family of Cortex M3 chips.

    Two highlights of his port, from my viewpoint, are

    • register allocation changes to improve code density
    • the inclusion of some automatic tests

    It is available at http://www.kudra.com/forth. I plan, eventually, to incorporate many of those changes into the main ARM and Cortex Riscy Pygness code base.

1.4 Older news

  • Bundle of Tools (see Download section below) makes it easy to install the cross-compiling ARM GNU toolchain and related system software.
  • The manual now describes how to run Riscy Pygness from a live CD or live USB stick.
  • Riscy Pygness has now been ported to the STM32 ARM Cortex M3 (see http://pygmy.utoh.org/riscy/cortex/).
  • For LED blinking examples for STM32 and LPC17xx ARM Cortex M3 chips see http://pygmy.utoh.org/riscy/cortex/). Caution From reports from several people, I likely have org'd some or all of the examples incorectly, failing to leave enough room for the vector table. If you have any trouble running the examples, consider org'ing the start of the code to a slightly higher address. I plan to take a careful look and rework the examples, eventually.
  • r p has ported Riscy Pygness to the mbed board (see http://mbed.org/cookbook/MbedForth).

2 Introduction

Riscy Pygness is a 32-bit multitasking Pygmy Forth for the ARM. It includes full source code for both the host (your desktop PC) and target (your ARM development board). The license is BSD/MIT-like so you can do (nearly) anything with it.

It is aimed at relatively small embedded systems rather than desktop systems or large embedded systems running an operating system (OS).

Riscy Pygness is a stand-alone system that is its own multitasking OS. It can run in about 4 K bytes of flash and about 1.5 K bytes of RAM. The size can be reduced further depending on your needs. This makes it suitable for use in even the smaller ARM variants such as the NXP LPC2101, LPC2102, and LPC2103. It can address the full 4 GB address space, so it can take advantage of all the flash and RAM available in even the larger variants.

During development, the host communicates with the target via a serial port. The host provides the smart terminal and the compiling services. The host can generate a new, customized Forth image for the target.

The Forth itself runs on the target but you interact with it by typing commands on the host, much as you would with a Forth running locally on the host.

As you type each word (command) at the terminal, the word is looked up on the host which then sends a request to the target to execute the word. Numbers typed at the terminal are sent to the target to be put on the target's data stack. Word headers are kept on the host, not the target, and all compilation work is done on the host.

The host and the target, working together, provide the effect of a fully interactive Forth running on the target while conserving the target's limited resources.

3 Download

Riscy Pygness
version released November 12, 2010

After downloading into your home directory, create a working directory and uncompress the files there, e.g.,

$ cd                                           # move to your home directory
$ mkdir riscy                                  # make a working directory
$ cd riscy                                     # move to the working directory
$ tar -xjvf ../riscypygness-20101113.tar.bz2   # uncompress the files
The Manual
the manual applies to the ARM as well as the ARM Cortex versions of Riscy Pygness
The Bundle of Tools
(the GNU toolchain to cross assemble for the ARM, Tclkit, lpc21isp).

Note, these tools were compiled under Ubuntu 10.04 i386 32-bit. They might work on Ubuntu 10.10 i386 32-bit or under other Linux distributions, possibly even on 64-bit versions if the 32-bit libraries are installed. Please let me know if you run it successfully on any Linux distribution other than 32-bit i386 Ubuntu 10.04.

the binary
http://pygmy.utoh.org/riscy/arm-toolchain.tar.bz2 (28M)
its checksum
http://pygmy.utoh.org/riscy/arm-toolchain.tar.bz2.md5

After downloading above, run

$ md5sum -c arm-toolchain.tar.bz2.md5   

to verify the checksum, then

$ sudo tar -xjvf arm-toolchain.tar.bz2 --absolute-names --keep-old-files 

to uncompress and install in the standard locations (under /usr/local/).

the source
since some of the above is licensed under the GNU GPL, the full source code for the GPL'd files is also available here. You probably do not need to download it unless you wish to compile the tools yourself.

4 How to get started

See the latest version of the manual.

5 Kernel images

Kernel images to be burned into flash on the ARM are included in the zip file for 4 Olimex boards.

  • Olimex LPC-P2106 board
  • Olimex LPC-P2103 board
  • Olimex LPC-P2378 board
  • Olimex LPC-P2294 board

It is very easy to add support for other LPCxxx-based boards and should be fairly easy to port to other ARM 7 variants.

6 A note about operating systems

I am running on Linux, typically Debian or Ubuntu.

Any Linux or Unix or Unix-like operating system that can run Tcl/Tk (i.e., all of them) should work great.

If you are not currently running Linux or Unix, you can try out Riscy Pygness from a live CD (details in the manual).

If you prefer to run on a Microsoft operating system, you probably can do so, but everything is likely to be just a little more difficult. It might be worth setting up a spare machine (or booting from a Live CD) to have Linux available. The manual has a section describing such alternatives.

7 Feedback

If you try Riscy Pygness, feel free to email me at frank@pygmy.utoh.org for with suggestions or questions. Your feedback will help me further improve the system and manual.

Date: 2011-10-31 Mon