Riscy Pygness User Manual

There are several ways to do this, such as

• boot a Linux live CD (such as the Ubuntu 10.04 LTS from http://www.ubuntu.com/desktop/get-ubuntu/download). Note, I recommend 10.04, since that is the version I used to compile the bundle of tools. Still, other versions of Ubuntu, or other live CDs, might work fine.

  You might tire of installing the bundle of tools everytime you boot, so I suggest putting the live CD onto a USB stick. See Putting Ubuntu on a USB stick. That way your the changes you make will be persistent.

• install Linux on an external disk drive (either a flash USB stick or an external USB disk drive). Then, boot to this external drive whenever you wish to work with Riscy Pygness.

Install Linux on some other computer than your main workstation. Then

• sit at this other computer to work with Riscy Pygness, or
• sit at your main workstation and connect to the other computer through your local network. You could think of this other computer as an adaptor that connects your ARM board to your main computer, even a main computer running a Microsoft OS. You would make this connection with the ssh program (the modern equivalent of telnet) or with VNC.

  Once Linux was installed, you wouldn't particularly need to leave a monitor or keyboard attached to the spare computer.

This spare computer can be almost any old junk computer you have lying around. In a pinch, you could get by with 128M of RAM and a small hard drive and possibly run Linux without a GUI (without the X Window system). It needs a serial port, but you could use a USB-to-serial cable.

The easy way is to download http://pygmy.utoh.org/riscy/arm-toolchain.tar.bz2 then uncompress it.

$ wget http://pygmy.utoh.org/riscy/arm-toolchain.tar.bz2
$ sudo tar -xjvf arm-toolchain.tar.bz2 --absolute-names --keep-old-files

The first line above downloads a bundle of tools and the second line uncompresses the bundle and places the tools where they should go.

It installs the following

• cross-compiling binutils to supply the ARM assembler, linker, etc.
• Tclkit to supply Tcl (the assembler pre-processor and the Riscy Pygness smart terminal/compiler are written in Tcl)
• lpc21isp (to download code to the ARM CPU's flash memory)
• GDB (the GNU debugger for the ARM) in case you wish to single-step through any assembly language code.

Note, this bundle of tools is compiled for a 32-bit version of Linux running on Intel (AMD, etc.) hardware.

The hard way would be to install and/or compile and install those tools yourself, one by one. In which case, you still might wish to download the bundle of tools and then run the following command to see which files and needed and where they go:

$ tar -tf arm-toolchain.tar.bz2

You also need to have an editor (I recommend Emacs) and the Make program. Maybe your version of Linux already has one or both of these. You can find out if they are installed by running

$ which emacs
$ which make

If not installed, install them with the package manager that your version of Linux uses. For example, if you are running Debian or Ubuntu, you could install them with

$ sudo apt-get update
$ sudo apt-get install emacs
$ sudo apt-get install make

Traditionally, Forth code was kept in "screens" or "blocks". Each was a fixed size of 1024 bytes (characters), presented to the user in an editor that showed 16 lines of 64 characters.

This size is very convenient for source code and encourages modularity and short definitions.

In Riscy Pygness, we fake true 1024-byte blocks by using a text file divided into logical blocks by special comment lines.

Each "block" starts with a special Forth comment in the first line. The left parenthesis must be in the first column, followed by a space and either the word "block" or the word "shadow", followed by a space and a decimal number (the block number). Additional text may follow, but the comment must end eventually with a right parenthesis.

When we LOAD a block, the host program searches for that marker to know where to extract the text to be interpreted.

The procedure filenameFromBlockNumber (near the top of riscy.tcl) maps block number ranges to file names. Edit it if you wish to add additional block files or to change the ranges.

Block numbers should be in numerical order, else searching might fail. However, "holes" (missing block numbers) are ok.

riscy.tcl reads the entire file into the host's memory, but only when the file changes.

Here are some examples of special comment lines that would mark the beginning of a block.

( block 0  )
( block 1   ------------------  load block)
( block 2  miscellaneous)
( shadow 2 )
( block 3  )

When you type a Forth command such as 22 LOAD, the procedure filenameFromBlockNumber finds that block 22 belongs to the file named kernel.fth. If this is the current file, then riscy.tcl has already read it into memory (on the host), otherwise it becomes the current file and is read into memory. Then, using the block comment lines, riscy.tcl finds the range of lines to load.

Using the forthblocks mode in Emacs, a single block is displayed at a time. PgDn (or C-v) moves to the following block. PgUp (or M-v) moves to the previous block. M-a ("a" for "alternate") toggles between a block and its corresponding shadow block. Traditionally, Forth code with short comments goes on the "block" and lengthier comments go on the "shadow".

What I usually do when I start a new Forth file is to write one comment line for a block and another for a shadow, e.g.,

( block 0 )
( shadow 0 )

Then copy and paste the two a bunch of times, producing something like

( block 0 )
( shadow 0 )
( block 0 )
( shadow 0 )
( block 0 )
( shadow 0 )
( block 0 )
( shadow 0 )

Then run the Emacs forthblocks mode command M-x renumber-blocks to fix up the numbers automatically, producing

( block 0 )
( shadow 0 )
( block 1 )
( shadow 1 )
( block 2 )
( shadow 2 )
( block 3 )
( shadow 3 )

See the file forthblocks.el for more details on how to set it up and use it.

Another traditional use of 1024-byte blocks is for data storage. This use is not particularly addressed by the text-file-based block system described in the previous subsection. Nothing precludes the possibility of using certain block ranges for text-file-based blocks for source code storage while using different block ranges for pure 1024-byte data blocks (located perhaps in RAM, flash, or SD cards).

Then, burn the *.bin (e.g., kernel-lpc2103.bin) into the ARM's flash with

$ make kernel-lpc2103.dl

Note that some flash utilities (for example, the lpc21isp flash utility when given the -control option) will control the serial port's DTR and RTS lines in an attempt reset the ARM while holding the bootloader request line low. This works only if your ARM board supports it. For example, on the Olimex LPC-P2378 board, short the two jumpers ISP_E and RST_E if you wish this to work. On hardware that does not support this, you need to change jumpers and/or push reset buttons manually in order for the bootloading to work.

On the Olimex LPC-L2294 board, it is probably best to leave RST_E open and to manually short the ISP_E jumper and press the reset button when downloading a program. Then, open the ISP_E jumper and press the reset button once again so the newly downloaded program can run.

Edit the following variables in makefile depending on the particular ARM chip, serial port, path to the assembler, etc. that apply to your environment.

The only ones you normally need to verify/edit are CCLK and PORT.

CCLK

the CPU clock speed of your board in KHz. This is used by both the lpc_prog and the lpc21isp flash utilities. Note that this is the external crystal speed when using the LPC2106 and some others but is always 14748 when using the LPC2378.

PORT

the full path of your PC's serial port, such as /dev/ttyS0 or COM1: for the first serial port.

BIN

the full path to the directory that contains the ARM assembler (arm-elf-as) and other binutils utilities such as arm-elf-objdump.

DLBAUD

the serial rate you wish to use for downloading. This defaults to 38400. Other possible speeds are 115200, 57600, 19200, 9600, 4800, etc.

PREASM

the full (or relative) path to the preprocessor that converts *.asm files into *.s files. Normally the executable file is preasm.tcl but you could write a replacement in Python or sed or whatever if you prefer. Its main purpose at the moment is to replace semicolons (my preferred comment character) with at-signs (the GNU ARM assembler's preferred comment character).

LNKFLAGS

this includes the link script as well as flags.

ASMFLAGS

flags passed to the assembler.

LNKFLAGS

flags passed to the linker.

ZIPFILES

a list of the files to be bundled together to create a Riscy Pygness distribution when I say make bzip. You would not ordinarily need to do this.

riscy.tcl program serves two purposes:

1. Create a kernel image file suitable for burning into the ARM chip's flash. This step also creates a matching dictionary file. The command line for this would be something like

   $ ./riscy.tcl -flash 1

   but you would not run this manually. It would be done automatically by the makefile.

2. Run Riscy Pygness interactively, using the dictionary file previously created, and the matching kernel image file previously burned into the ARM chip's flash. For example, if the kernel image and dictionary files are named kernel-lpc2106.bin and kernel-lpc2106.dictionary, your command line would be

   $ ./riscy.tcl -image kernel-lpc2106 -port /dev/ttyS0

   to run interactively (using the /dev/ttyS0 serial port). Of course, you could set up a shell script or alias to reduce your typing. See the shell scripts r and burn for examples.

See below for more information and/or run riscy.tcl file with no arguments to see a help message describing how to use it.

There are certain variables (and one procedure) in riscy.tcl that you should verify or change to suit your environment. All of these are located near the top of the file.

isUnix

Set to 1 to run on Linux (or other Unixes). If you wish to try running this on a Microsoft OS, change its value to 0.

::debug

Leave this set to 0 for normal use. Changing it to 1 causes (way too many) debugging messages to be printed. This setting can also be changed interactively with the Forth word DEBUG.

::serialPort1

Set this to the name of the serial port you use to connect to the target ARM board. Under Linux, this is usually either /dev/ttyS0 or /dev/ttyS1. Instead of setting it here, you can can specify it with the -port command line option, which will override the setting inside the program.

::baudrate

Set this to the same baud rate that the ARM chip is set to use. For the pre-built kernels, this is 38400 bps.

filenameFromBlockNumber

This procedure maps Forth block numbers to file names. You may add additional ranges and file names or change the existing ranges. It is best not to change the first one, which maps the first thousand blocks (0 through 999) to the filename kernel.fth.

I download code to be burned into the onboard Flash using the chip's built-in bootloader combined with Martin Maurer's lpc21isp flash utility program that runs under either Linux or Microsoft Windows.

Martin Maurer's lpc21isp is available from http://tech.groups.yahoo.com/group/lpc21isp (the Yahoo lpc21ispgroup) and a version is also included on the Riscy Pygness web site.

I run it to download the binary file kernel-lpc2106.bin, with the command

$ lpc21isp -verify -bin kernel-lpc2106.bin /dev/ttyS0 38400 14746

where /dev/ttyS0 is the serial port I am using and 38400 is the baud rate and 14746 is the speed of the crystal in KHz of the board I'm using (i.e., 14.746 MHz).

Download the source, unzip it into /usr/local/src, then compile it, then soft-link it into the /usr/local/bin directory.

It is a very easy compile. Just unzip, cd to its directory, then type make. Then, make sure the resulting binary is in your path. (Of course, you have to have make and a C compiler installed.)

What I do is to unzip it (untar it, whatever) into /usr/local/src/ which creates a subdirectory named lpc21isp. Then I rename that subdirectory to include its version number, e.g.,

# mv lpc21isp lpc21isp_179

Then I cd to that directory and run make. This produces the binary /usr/local/src/lpc21isp_179/lpc21isp. Then I soft-link it to /usr/local/bin/lpc21isp so it will be in my path.

# ln -s /usr/local/src/lpc21isp_179/lpc21isp /usr/local/bin/lpc21isp

I am using version 1.79. Here is the source code:

http://pygmy.utoh.org/riscy/lpc21isp-1.79.tar.gz

You can look for newer source either in the Yahoo lpc21isp group or at http://sourceforge.net/projects/lpc21isp/.

First, orient your board so "Olimex" reads correctly from left to right, then the serial connector is at the top left and the power connector is at the top right and the blank wire-wrap area is at the bottom.

Here is how I have my board jumpered:

• Debug (upper right corner) is open.
• J1 (middle of top edge) is open.
• LED_J (just to the right of the red LED) is shorted.
• BSL (top left) is closed when programming the flash and open when not programming the flash

Then I open a terminal and get my lpc21isp command ready to go, but don't hit RET yet. Then, I short the BSL jumper. Then I press RET at about the same time I press and release the reset button on the board (RST is the small push button just to the right of the CPU chip).

After successfully downloading to the flash, the lpc21isp program may say it has jumped to the program, but of course it has not, and cannot, because BSL is still shorted. Once the flash has been programmed, I open the BSL jumper and press the reset button again. If all is well, the LED should blink 6 times (because riscy.asm contains the code to blink the LED 6 times).

lpc2k_pgm

http://www.pjrc.com/arm/lpc2k_pgm

lpc_prog

http://www.blisstonia.com/software/lpc_prog_20060709.tgz by Edwin Olson, license GPL, per his posting to the lpc2000@yahoogroups.com mailing list. (There may be newer versions by the time you read this). The '2006' is a typo in the file name and the referenced file is the version that was current as of July 9, 2007. (I have used the earlier version of 20070503 successfully with the lpc2378.)

This gives you a place to type commands. (Actually, the commands are typed into the shell program, typically bash, that is running in the terminal.) I usually run the program gnome-terminal for this, but any such terminal program will work.

In this manual, often the commands to be typed will be shown preceded by $ or #. Do not type this initial $ or #. It merely represents the terminal's (the shell's) prompt. # indicates the command is typed as the superuser. $ indicates the command is typed as an ordinary user. Note that a # appearing later in the command is completely different: it means the rest of the line is a comment (and you would not type the comment).

See terminal above.

See terminal above.

See terminal above.

To list the contents of a directory (in a terminal), type

ls -als

To see the various options for the ls command, type

man ls

I usually set up a dir alias so that when I type dir, what gets executed is ls -als. Such aliases are typically set up by editing your ~/.bashrc file, but they can be set up on the fly at a command prompt, e.g.,

alias dir='ls -als'

Some commands need to be typed as the superuser (also known as root).

Some Linux distributions use a root account with a password. In that case, type su then enter the password when prompted.

In other Linux distributions, you may need to type something like:

 $ sudo -i

or

  $ sudo su

Otherwise, look for how to do it in your distribution's documentation or on Google.

I use this as a general term for uncompressing a compressed file, regardless of whether it was zip'd, tar'd, gzip'd, bzip2'd, etc. The extension on the file generally indicates which program you should use. Here are some examples:

xyz.zip

unzip xyz.zip

xyz.tar

tar -xvf xyz.tar

xyz.tar.gz

tar -xzvf xyz.tar.gz

xyz.tar.bz2

tar -xjvf xyz.tar.bz2

If in doubt about the type of file, run the file command on it. E.g., file xyz.zip should indicate that it is a zip file.

This is sometimes referred to as a symlink or a symbolic link. It let's you store a file somewhere (perhaps /usr/local/src/lpc21isp_179/lpc21isp) yet refer to it via a directory that is in your path, such as /usr/local/bin/lpc21isp.

We could set up the above link this way (as root):

# ln -s /usr/local/src/lpc21isp_179/lpc21isp  /usr/local/bin/lpc21isp

If we later install a newer version, say as /usr/local/src/lpc21isp_180/lpc21isp, we can change the soft link with

# ln -sf /usr/local/src/lpc21isp_180/lpc21isp  /usr/local/bin/lpc21isp

(Here we added the -f option to "force" the overwrite of the existing link.)

Another place we do this is with Tclkit.

This refers to a file name, including the directory information needed to find it. The path can be absolute, such as /usr/local/bin/tclkit (note the leading /) or it can be relative to the current directory, such as tclkit (note the absence of a leading /).

This is your ARM board

This is your Linux desktop (or laptop or whatever) computer.

The typical Linux computer is filled with documentation.

• Look for a doc directory, e.g., /usr/share/doc/ and then for a subdirectory named after the program you want documentation for, e.g., /usr/share/doc/openocd/.
• the man command (short for "manual"), e.g., man openocd or man bash or man ls
• the info command, e.g., info emacs
• the apropos command, e.g., apropos terminal, to give you clues as to which programs on your system my be appropriate.
• the search function within your Linux package manager (such as synaptic in a Debian or Ubuntu system). This can give you ideas as to what programs (already installed or not) might be useful.

Google or some other search engine should take care of anything else. For example, in the Getting started section, there is a mention of shell aliases. If you do not know what that means, you could Google for "shell aliases".

This manual uses the Emacs convention for representing keystrokes. For example, C-c means to press and release the "c" key while holding down the Control key. Below are some more examples, but for a full description, run the Emacs tutorial (from within Emacs).

C-h

while holding down the Control key, press and release the "h" key.

C-ht

Control h followed by t (within Emacs, this starts the tutorial)

RET

press the Return (or Enter) key

M-x

while holding down the "meta" key (i.e., the Alt key on most keyboards), press and release the "x" key.

Riscy Pygness works well on this chip and board. The main Riscy Pygness download also includes led1-2103.asm as a small test program to flash the Olimex board's LED, as a way of verifying the board and your connections to it.

What about board jumper settings? This is what worked for lpc21isp:

DBG_E

shorted or open

JTAG cable

plugged in or not

JRST

open

BSL

shorted when running lpc21isp but open to then run the Forth

Note, however, that if OpenOCD had been running, you have to power off the ARM board after killing OpenOCD. It is not enough to merely press the reset button; the board must be power cycled.

For JTAG, something like

$ openocd -f interface/olimex-jtag-tiny.cfg -f target/lpc2103.cfg

might do it. Note, though, that the lpc2103.cfg file has this line

flash bank lpc2000 0x0 0x8000 0 0 0 lpc2000_v2 12000 calc_checksum

but my Olimex LPC-P2103 board has a 14.7456 crystal.

So, I created a custom lpc2103.cfg file in my working directory that changes the flash line to

flash bank lpc2000 0x0 0x8000 0 0 0 lpc2000_v2 14746 calc_checksum

and I also added this line

jtag_khz 50

to slow down the interface enough that it would work.

For this to work, I short the DBG_E jumper (and, of course, I plug in the JTAG cable).

Note, sometimes I need to start the openocd program more than once before it finally comes up without errors. I suppose I could make it more likely to work by reducing the jtag_khz 50 line even further.

The button on this board is normally open. The button signal is pulled up, so it is normally high. When the button is pressed, it shorts the button signal to ground. The button signal is connected to U1 (the LPC2103 chip) pin 45, P0.15/EINT2/RI1.

See custom-lpc2103.asm. That pin (P0.15), as with all the I/O pins, has been configured as an I/O pin and is an input pin, which is just what we want. We also use the fast I/O facility.

So, for example, to read the button we could use

  : BIT15 ( - mask)  $00008000  ;
  : BUT? ( - f) FIO0PIN @ BIT15 AND 0= ;  ( returns true if the button is pressed)

Here are some thumbnails (just click on them to see the full size images) of the Olimex LPC-P2106 board and my MMC/SD interface to it.

The main Riscy Pygness download includes led1-2378.asm as a small test program to flash the Olimex board's LED.

Pin-out diagrams for the connectors on the Olimex LPC P2378 development board.

Fortunately, OpenOCD comes with a good user manual. OpenOCD comes with some prewritten configuration files. If configuration files for your board and/or ARM variant are present (in /usr/share/openocd/scripts/ on an Ubuntu system), running it can be as simple as specifying one config file for your JTAG cable and another for your board, e.g., if you use the same JTAG cable I use and an Olimex LPH-H2148 board, you would start OpenOCD in a terminal with this command:

$ openocd -s /usr/share/openocd/scripts -f interface/olimex-jtag-tiny.cfg -f board/olimex_lpc_h2148.cfg

OpenOCD version 0.2.0-in-development (2009-06-30-01:11) does not come with configuration files for the Olimex LPC-P2106 board or chip, so I created a target config file named lpc2106.cfg based on a similar target config file. I hope to post it to the OpenOCD site, so perhaps it will be included in a future OpenOCD version. Meanwhile, you can use it directly from within your working directory. The idea is that its path would eventually be /usr/share/openocd/scripts/target/lpc2106.cfg.

Rather than typing a long command line such as

$ openocd -f /usr/share/openocd/scripts/interface/olimex-jtag-tiny.cfg -f lpc2106.cfg

I created a config file named openocd2106.cfg that goes in my working directory. The file, at a minimum, has these contents:

# This file is for use with the Olimex LPC2106 board.  
# It is named openocd2106.cfg.  Run it this way:
#    $ openocd -f openocd2106.cfg

# This is the JTAG connector I use
source [find interface/olimex-jtag-tiny.cfg]

# The following file, for now, is in my current directory
source [find lpc2106.cfg]

Once you run openocd -f openocd2106.cfg in a terminal, OpenOCD is running as a daemon. To kill it, type C-c in the terminal.

Sometimes I need to start it several times before it comes up without any error messages. (Start it, see errors, kill it. Start it, see errors, kill it. Start it, no errors, good, leave it running.) You need to have the JTAG cable connected, and the DEBUG jumper (labeled "DEBUG" on the LPC-P2106 board) shorted.

After starting OpenOCD running as a daemon as described in the previous section, you can open a new terminal and connect via telnet;

$ telnet localhost 4444

See the OpenOCD manual for the commands you can use. Following are some examples.

• Miscellaneous
  

  > poll
  > reg
  > reg r0
  > reg pc
  > reg r0 0x12345678
  > reg r0
  > halt
  > resume
  > step [address]
  > step 0
  > reset
  > reset run
  > reset halt
  > (for memory display of word, half-word, or byte, use 'mdw addr [count]' etc.)
  > mdw 0 8
  > mdb 0 32
  > (for writing, use 'mww addr value', 'mwh addr value', 'mwb addr value')
  > mww 0x40000000 0x12345678
  > mww 0x40000004 0x55553333
  > mdw 0x40000000 4
  > armv4_5 disassemble 0 20
  > arm7_9 fast_memory_access enable
  > flash banks
  > flash info
  

• Dump the flash contents
  

  Here is an example to verify the contents of the flash. I (thought I) had programmed the flash with the file kernel-lpc2106.bin, a 3584-byte file at the time. So, I wanted to dump the first 3584 bytes of the flash to another file so I could compare the two files.

  I dumped the flash to a file named dump1.bin, via OpenOCD with

  $ dump_image dump1.bin 0 3584
  

  Then I compared the original file kernel-lpc2106.bin with dump1.bin with the hexdiff program, i.e.,

   $ hexdiff kernel-lpc2106.bin dump1.bin
  

  Note, if the only difference is the 4 bytes at address 0x00000018, that is not necessarily a problem. Those 4 bytes hold a checksum (the 32-bit two's complement of the sum of the other 7 vectors) used by the LPC2106 bootloader. So, if you add all 8 vectors, you should get a number whose rightmost 32 bits are zeroes. riscy.tcl calculates this checksum automatically when it creates a kernel image.

• Erase flash sector 0
  

   flash erase_check 0 
   flash protect_check 0
   flash info 0
   flash protect 0 0 0 off    # if sector 0 had been protected
   flash protect_check 0
   flash info 0
   flash erase_sector 0 0 0
  

  The first command lists the sectors of bank 0 to see which are already erased. The second erases, in bank zero, all the sectors from number zero through number zero. I.e., it erases sector 0.

  Note, on the LPC-P2103 (and probably on the LPC-P2106) it never shows the protection turned off, yet that did not prevent me erasing or reprogramming sectors.

• Reprogram the flash
  

  flash write_bank 0 kernel-lpc2106.bin 0
  

  This reflashes the chip with the Riscy Pygness kernel into bank 0 starting at offset 0.

Here's an example of using GDB to step through the Forth word C@ on the Olimex LPC-P2103 board, which uses the NXP LPC2103 ARM chip.

First start OpenOCD as described earlier. I open a terminal, cd to my working directory, and start OpenOCD with

$ openocd -f openocd2103.cfg

If it reports errors, kill it (with C-c) then try again, until it comes up with no errors. I have sometimes needed to alter the jtag_khz xx setting to slow down the clock, e.g., jtag_khz 32. Once it starts sucessfully, you can ignore this terminal.

Then start up Emacs in another terminal (or wherever), if not already running. Edit the .gdbinit file in the working directory to be sure GDB will cd to your correct working directory and to open the correct *.elf file – look for a line like

file ~/riscy/lpc2103/riscy-lpc2103.elf

Then, start GDB with M-x gdb and specify

arm-elf-gdb --annotate=3

as the actual GDB command to run.

At this point, we have one terminal running OpenOCD as a daemon in the background. This terminal does not need any further attention. Then, we have Emacs running (in a terminal or in its own window) with GDB running in the Emacs *gud* buffer, where we will interact directly with GDB.

We then start another terminal in which to run Riscy Pygness. This terminal may actually be a shell running inside another instance of Emacs (to give us convenient command recall and command completion) or it could be your usual terminal program (such as gnome-terminal). At some point, we start Riscy Pygness in this terminal, with

$ ./riscy.tcl -image kernel-lpc2103 -port /dev/ttyS0

Since we wish to step through the code for C@, we need to find its address and tell GDB to set a breakpoint there.

There are two ways to find this address. One is from within Forth by running

' C@ .H

(which prints the address in hexadecimal). The other is by consulting the linker listing from when the Forth kernel was generated. In this example, that file is named riscy-lpc2103.lnkt. We won't find C@ listed under "C@" here (although we would find DUP listed under "DUP"). The reason is that "C@" is not a valid label name to the assembler. If we search for "C@" in riscy.asm, we will discover the label name used for the Forth word C@ is "Cfetch". (Thus, we would search for "Cfetch" when looking in the linker file.) In this example, its address is 0x0374. Since our .gdbinit file sets the radix to hexadecimal, within the *gud* buffer, we can specify that address as 374.

Note, since we told Emacs to open the file riscy-lpc2103.elf it knows to find the source code in the file named riscy-lpc2103.s (which was derived by preprocessing the file riscy-lpc2103.asm which was derived from riscy.asm by including the proper include files for the LPC2103 chip). As you jump and step within the *gud* buffer, a marker should move around accordingly in the riscy-lpc2103.s buffer.

In the Emacs *gud* buffer, set the breakpoint:

 mon poll        # make sure the ARM is halted
 mon reset halt  # in case above showed it was not halted
 i b             # show current breakpoints
 del 2           # delete any other than the one at _start (at 0x20)
 i b             # confirm only the one at 0x20 is set
 b Cfetch        # set our second breakpoint at the start of the C@ primitive 
 j _start        # jump to the start of the program
 c               # "continue" to start the program running so our Forth buffer can run

Then, in the Forth buffer, type some command involving C@ to make it hit the breakpoint, if it has not already stopped at that breakpoint, such as $4444 C@.

Then, back in the Emacs *gud* buffer, examine registers, single step, etc. See the GDB users manual for details.

 p $r0           # display register zero (which holds the top-of-stack)
 s               # single step
 ...             
 i reg           # show values (and names) of the CPU registers
 p $cpsr         # display the condition code register
                 #   the left 4 bits (NZCV) are often the most interesting
                 #     bit 31  N
                 #     bit 30  Z
                 #     bit 29  C
                 #     bit 28  V
                 # e.g., 0x200000d3 means the carry bit is set
 display $r1
 display $r2
 display $cpsr
 display $r0     # set up the 4 values we wish to see after every step command

Emacs has extensive built-in help. If you are not yet familiar with Emacs, start it up and work through its built-in tutorial. Start the tutorial by pressing C-h t (i.e., press control h then press t) or by clicking on the **Help** menu and choosing **Emacs Tutorial**.

The file forthblocks.el (in the distribution) is an Emacs mode for editing Forth. Put that file into your home directory.

Put the following into your ~/.emacs file so the forthblocks mode will be run automatically when you open a file whose name ends in .fth.

(setq auto-mode-alist
      (cons '("\\.fth" . forthblocks-mode) auto-mode-alist))
(autoload 'forthblocks-mode "~/forthblocks.el" "Forth blocks editing mode." t)

If you don't yet have a .emacs file, copy the example file to your home directory. It already contains the above lines.

$ cp ~/riscy/.emacs-example ~/.emacs
$ cp ~/riscy/forthblocks.el ~/

Read the file forthblocks.el for details. The quick summary is that it works with plain text files (not traditional Forth 1024-byte blocks) but simulates blocks by recognizing comments such as

( block 1   ------------------  load block)
( shadow 1 )
( block 2  miscellaneous)
( shadow 2 miscellaneous )

as block markers. This gives you "logical" blocks which should be kept short, but are variable length. For me, this gives a pretty good compromise for source code: modular Forth blocks and the ability to use my favorite text editor.

See forthblocks.el for the keystrokes that move from block to block, that toggle between a block and its associated shadow block, that renumber the blocks, etc.

If you really don't like even this form of blocks, then just put a single block comment at the top of the file, such as

( block 2000   everything in this file is in block number 2000)

then everything in the file will be in a single (gigantic) block. To load the entire file, say

2000 LOAD

See also riscy.tcl for how to map block ranges to file names.

In order to create a new kernel, you need to have at least parts of the GNU Toolchain for the ARM installed. In particular, you need the assembler, linker, and some object file manipulating utilities – all of which are bundled together in the binutils package.

Your two main choices are to install a pre-compiled GNU tool chain or to compile the binutils software yourself.

Binutils is very easy to compile. That is the only part of the tool chain you really need in order to work with Riscy Pygness. You might also wish to compile the GNU debugger. You do not need the C compiler for the ARM.

If compiling from source, you might find the Lewin Edwards book Embedded System Design on a Shoestring helpful, although it isn't needed if you are compiling just binutils.

Here is an example of how to compile binutils.

First, download the source from http://ftp.gnu.org/gnu/binutils/, choosing one of the more recent versions, such as http://ftp.gnu.org/gnu/binutils/binutils-2.18.tar.bz2.

In general, for each package, I download the *.tar.gz or *.tgz source code package and uncompress it in /tmp, e.g.,

# cd /tmp
# tar -xzvf binutils-2.15.90.0.1.1.tgz

then create a build directory at the same level, e.g.,

# cd /tmp
# mkdir binutils-make

then configure, compile, and install the package, with something like the following

# cd binutils-make
# ../binutils-2.15.90.0.1.1/configure --target=arm-elf --prefix=/usr/local/arm
# make
# make install

Of course, adjust the file names to suit the actual version you are compiling and installing.

Note, you must be root, at least for the install step. See the section on becoming root.

Then, if you want to compile gdb or insight (insight contains gdb, so no need to compile both of them), do it generally as above but with a configure command such as

# ../insight-6.1/configure --target=arm-elf --prefix=/usr/local/arm/

Here are some notes about generating the bundle of tools (http://pygmy.utoh.org/riscy/arm-toolchain.tar.bz2). I used Ubuntu 10.04.1 which comes with make and gcc but we need to install the texinfo and libncurses-dev packages for the compiles to succeed.

• Compiling binutils
  

  I downloaded the source from http://ftp.gnu.org/gnu/binutils/.

  # apt-get install texinfo
  # cd /tmp
  # mkdir binutils-build
  # cd binutils-build
  # make /usr/local/src/binutils-2.20.1/configure --target=arm-elf --prefix=/usr/local/arm
  # make
  # make install
  

• Compiling GDB
  

  The most recent version appears to be version 7.2 of 2 Sept 2010. If we want Insight, then we get an older version of GDB (6.8). I chose to build just the newer GDB and forget about Insight. If we run GDB, we will do so from within Emacs.

  I downloaded the source from http://ftp.gnu.org/gnu/gdb/gdb-7.2.tar.bz2.

  # apt-get install libncurses-dev
  # cd /usr/local/src
  # gpg --verify gdb-7.2.tar.bz2.sig gdb-7.2.tar.bz2
  # tar -xjf gdb-7.2.tar.bz2
  # cd /tmp
  # mkdir gdb-build
  # cd gdb-build
  # /usr/local/src/gdb-7.2/configure --target=arm-elf --prefix=/usr/local/arm
  # make
  # make install
  

• Compiling lpc21isp
  

  I downloaded lpc21isp-1.79.tar.gz into /usr/local/src/ and then compiled it and linked to a shorter name. The process was approximately the following (I don't think it needed a configure or install step, but I might have misremembered).

  # cd /usr/local/src/
  # tar -xzvf lpc21isp-1.79.tar.gz
  # cd lpc21i*
  # make
  # cp lpc21isp-1.79 /usr/local/bin
  # ln -s /usr/local/bin/lpc21isp-1.79 /usr/local/bin/lpc21isp
  

  See also the notes here at *Compiling lpc21isp.

One symptom might be that things suddenly make no sense.

You've been working away with Riscy Pygness and your target ARM board, then you make a change, reflash the target, and nothing seems to work quite right. What could it be?

I'm not even going to mention the possibility that you forgot to turn on the power or perhaps left the boot jumper shorted after flashing.

One possibility is that the target's flash did not actually get programmed correctly. I believe I had this happen when flashing with version 1.48 of the lpc21isp, even though I used the -verify option. lpc21isp should have complained, but, no, it just silently pretended the flashing had succeeded.

To verify the flash was not programmed correctly, I used the JTAG interface and OpenOCD. First, I was single stepping through the code and the wrong value for the flash token table appeared to be loaded. That was my first clue.

Then, I used OpenOCD to dump the actual contents of the flash to a file and then compared that with the original kernel-lpc2106.bin, using a program named hexdiff. The two files should have been identical (other than perhaps the checksum vector at address 0x00000018), but they were not.

To fix it, I then used OpenOCD to erase the flash and then used OpenOCD to reprogram the flash. Then things worked properly once more.

See the JTAG section for details on how to dump, erase, and reprogram the flash.

I upgraded to version 1.79 of lpc21isp and tried again with the same board. This version, fortunately, actually verifies the flash. It warned me that it couldn't program a sector, rather than failing silently.

See the label blink: in riscy.asm. This routine blinks an LED on the target board (if the board and the custom-*.asm file support this). Near the start of the routine the count is set. You can change how many times the LED blinks. If, when you reset the board, you see the LED blink the appropriate number of times, then you know the program has progressed to that point.

As distributed, Riscy Pygness is set to use a serial port speed of 38,400 bps. This is a conservative value and you probably could increase it to 115,200 bps. If you change it, be sure to change it everywhere: makefile, riscy.tcl, and custom-*.asm.

See the label greet: in riscy.asm. Prior to blinking the LEDs, the target sends a greeting out the serial port. The greeting consists of a CRLF (carriage/linefeed), followed by "hi", followed by CRLF.

In normal use, i.e., starting the program with

./riscy.tcl -image kernel-lpc2103 ...,

you will not see this greeting because riscy.tcl silently eats the greeting (since it is waiting for a properly formatted message from the target and the greeting is deliberately not so formatted).

However, if you are having trouble with the serial communication, you can start a serial terminal program such as minicom instead of riscy.tcl. Then, when you boot or reset the target, you should see the greeting in the serial terminal. If you do not see the greeting, check your cables and check your settings in minicom. Are you using the correct serial port name? Have you set the baud rate correctly (this should be 38,400 bps unless you have changed it everywhere)? 8 data bits, no parity, 1 stop bit? Have you turned off both hardware and software flow control? Until you see the greeting, there is no point in wondering about why the Forth itself doesn't work.

I have run into the problem after rebooting the host where the host programs (either riscy.tcl or lpc21isp) were unable to set the baud rate. With riscy.tcl, the symptom is that, although a message such as

  Welcome to Riscy Pygness
  Loading the dictionary from kernel-lpc2103.dictionary

appears as usual, the expected prompt never appears. That is, this is what should appear

  Welcome to Riscy Pygness
  Loading the dictionary from kernel-lpc2103.dictionary
  >

A cure for this is to bring up minicom and set the baud rate to 38400 then exit minicom. I imagine this will last until the host is rebooted. Thus, you probably only need to do this once each time you reboot the host.

Be sure not run minicom and riscy.tcl at the same time (as they will fight each other for control of the serial port).

I have had a report that the mbed board works better if the serial port is set to 2 stop bits in riscy.tcl. I expect I will make that change, but, meanwhile, if you run into trouble, try changing it yourself.

If you see errors like this when trying to assemble a kernel

riscy-lpc2294.s:281: Error: register expected, not 'DSTK,=dstk1' -- `ldr DSTK,=dstk1'
.....
riscy-lpc2294.s:1733: Error: register expected, not 'DSTK,#-4]!' -- `str r1,[DSTK,#-4]!'

[FIXME] the solution is probably [to be filled in later]

I have had a report that the "-donotstart" option is required in some cases (even though I don't see why it should ever be needed). So, if you have trouble with lpc21isp, add the "-donotstart" option to see if it helps.

Riscy Pygness should be easy to port to any ARM processor (ARM 7, ARM9). So far, I have run it on the NXP LPC family of ARM processors. It currently runs on at least the LPC2106, LPC2103, LPC2294, and the LPC2378. The modifications necessary for other LPC ARM7 processors should be minimal. It has not yet been ported to the ARM Cortex.

Riscy Pygness currently works on at least the following ARM CPU and board variants.

• Olimex LPC-P2106 board
• Olimex LPC-P2103 board
• Olimex LPC-P2378 board
• Olimex LPC-P2294 board
• New Micros Tini2106 board

We can expect it to run on the entire LPC family of chips with minor adjustments for clock speed, and such, on specific boards.

Riscy Pygness has now been ported to several ARM Cortex variants, including the LPC17xx and the STM32 families. See http://pygmy.utoh.org/riscy/cortex for more information.

r p has ported it to the MBED board. See http://mbed.org/cookbook/MbedForth for more details.

The Appendix includes some information for several variants.

I have attempted to isolate the CPU-specific and/or development board-specific part of the code in separate files. See custom-lpc2106.asm, custom-lpc2103.asm, and custom-lpc23xx.asm in the distribution. The main assembly language file, riscy.asm, contains one conditional directive which includes the appropriate CPU-specific file based on a symbol defined near the top of riscy.asm. The makefile edits that symbol automatically to match the particular processor.

The file equates-lpc2xxx.asm holds register definitions that apply to all of the NXP LPC2000 family members. In addition, there are board-specific equates files: olimex-lpc2106-equates.asm, olimex-lpc2103-equates.asm, and olimex-lpc2378-equates.asm.

To port to a different ARM 7 or ARM 9 processor, copy whichever of the above files are most similar to your processor, and modify them. The goal, of course, is to isolate the parts that change from the parts that do not change, thus not cluttering the main source code with tons of conditional directives.

The main task will be to adjust for differences in how I/O and peripherals are handled, setting the clock speed, noting which pin (if any) connects to an LED, etc.