Building Kestrel 2DX

As it's currently implemented, the Kestrel 2DX only runs on the now discontinued Digilent Nexys-2 FPGA board. Nothing fundamentally prevents it from being ported to another board, except my own limited resources.

Note that building a Kestrel 2DX from scratch involves three major steps: you must build the system firmware, then you must first build the hardware, and finally, you must build the Forth environment that it's intended to run.

If you're the impatient type like I am, you'll want to follow the Quick Build instructions. However, if you want to customize the design or otherwise contribute to its development, then you'll want to follow the Developers Build instructions.

Building for Digilent Nexys-2 with XC3S500 FPGA

Unfortunately, this FPGA is too small to hold the current Kestrel 2DX design. This is due to the current design which synthesizes its ROM, rather than relying on the on-board flash memory.

Quick Build Instructions

These instructions assume you are using a Linux operating system. I can't imagine that the instructions would differ greatly for BSD-type operating systems. However, as I don't have a BSD environment to test with, I cannot be certain of this. Please accept my apologies in advance. I similarly do not have any Windows computer to try these steps on.

Non-Destructive Programming

The instructions below will show you how to prepare your Nexys-2 board to run the latest Kestrel 2DX design and system software in such a manner that it does not affect the currently resident FPGA bitstream in serial flash. This approach has the advantage that you can try out the Kestrel 2DX without risk to your current design. However, since the design is only stored in RAM, it has the disadvantage that, after removing power, the Kestrel 2DX design will be lost and your previously flashed design return upon restoring power.

Two major steps are required to build a working system. First, you must create a bootable Forth image for the Kestrel BIOS to read in. The second is reprogramming the FPGA board itself.

NOTE. These steps assume you are running as root user!

Boot Medium Preparation

NOTE. After following these steps, your SD/MMC card will not be usable as a normal Linux or camera storage medium, and the data once on it will be destroyed. The Kestrel-2DX performs raw block I/O on the card, and does not understand any particular filesystems.

Download the SD/MMC card image kestrel-2dx-forth.img to your computer. You can name it whatever you like; but, the instructions which follow assume you'll keep the name listed here.
Insert a blank SD/MMC¹ card into your computer's SD card slot. Important! It is vital that your card not exceed 2GB in size. Larger cards use a different protocol than what the Kestrel's BIOS supports.
Your SD/MMC card may be pre-formatted with a FAT, exFAT, or VFAT partition. If so, and if you're running a popular OS distribution, you'll want to umount (unmount) all of the partitions your OS auto-mounted for you first. This will prevent your OS from inadvertently destroying the contents of the card after the next step. For example, on my computer, I'd use: umount /dev/mmcblk0p1. Do this for every partition it auto-mounts.
On my computer, Linux refers to the SD/MMC card as /dev/mmcblk0. Your computer may differ; consult the output of dmesg or mount for details. Once you know how your computer refers to the physical SD/MMC card, then as root user, run: dd if=kestrel-2dx-forth.img of=/dev/mmcblk0 (making sure to use the correct device name for of= clause).
Just for good measure, run sync to make sure all buffers are properly flushed before pulling the memory card out.

After this step completes, your SD/MMC card should contain a copy of the most recent Kestrel-2DX Forth system software image.

Programming the Nexys-2

The next step is to actually program your Digilent Nexys-2 FPGA board.

Download the kestrel-2dx-nexys2-jtag.bit file.
On your Digilent Nexys-2 board, make sure that jumper JP9 is set to JTAG.
Run djtgcfg enum . On my system, the FPGA board will have the "user name" of "Nexys2".
Run djtgcfg init -d Nexys2. On my system, the FPGA is at JTAG index 0.
Run djtgcfg prog -d Nexys2 -i 0 -f kestrel-2dx-nexys2-jtag.bit (assuming your JTAG is also at index 0). Use -i 1 if for some reason your FPGA appears at index 1.
After programming completes, push BTN0 to hard-reset the computer.

Proceed to the section after next to verify correct operation.

Flash (Destructive) Programming

The instructions below will show you how to prepare your Nexys-2 board to run the latest Kestrel 2DX design permanently, or at least until you re-flash it again. The Kestrel-2DX will come up upon restoring power to the Nexys-2 board.

Two major steps are required to build a working system. First, you must create a bootable Forth image for the Kestrel BIOS to read in. The second is reprogramming the FPGA board itself.

NOTE. These steps assume you are running as root user!

Boot Medium Preparation

Download the SD/MMC card image kestrel-2dx-forth.img to your computer. You can name it whatever you like; but, the instructions which follow assume you'll keep the name listed here.
Insert a blank SD/MMC¹ card into your computer's SD card slot. Important! It is vital that your card not exceed 2GB in size. Larger cards use a different protocol than what the Kestrel's BIOS supports.
Your SD/MMC card may be pre-formatted with a FAT, exFAT, or VFAT partition. If so, and if you're running a popular OS distribution, you'll want to umount (unmount) all of the partitions your OS auto-mounted for you first. This will prevent your OS from inadvertently destroying the contents of the card after the next step. For example, on my computer, I'd use: umount /dev/mmcblk0p1. Do this for every partition it auto-mounts.
On my computer, Linux refers to the SD/MMC card as /dev/mmcblk0. Your computer may differ; consult the output of dmesg or mount for details. Once you know how your computer refers to the physical SD/MMC card, then as root user, run: dd if=kestrel-2dx-forth.img of=/dev/mmcblk0 (making sure to use the correct device name for of= clause).
Just for good measure, run sync to make sure all buffers are properly flushed before pulling the memory card out.

After this step completes, your SD/MMC card should contain a copy of the most recent Kestrel-2DX Forth system software image.

Programming the Nexys-2

The next step is to actually program your Digilent Nexys-2 FPGA board.

Download the kestrel-2dx-nexys2-rom.bit file.
On your Digilent Nexys-2 board, make sure that jumper JP9 is set to ROM.
Run djtgcfg enum . On my system, the FPGA board will have the "user name" of "Nexys2".
Run djtgcfg init -d Nexys2. On my system, the flash ROM is at JTAG index 1.
Run djtgcfg prog -d Nexys2 -i 1 -f NEXYS2.bit (assuming your flash is also at index 1). Use -i 0 if for some reason your flash appears at index 0. NOTE: This will not cause the design currently in the FPGA to be replaced.
After programming completes, power-cycle the Nexys-2 to bring the Kestrel-2DX up.

Bootstrapping the Kestrel-2DX

At this point, the VGA monitor attached to the FPGA board should show the current BIOS version and be waiting for TIM/V commands. You should also have a PS/2 keyboard attached.

If you then attach an SD card reader to PMOD port JA1, insert the Forth SD card into it, then type the following:

i
l 14300,0,20
g 14300

You should be greeted with a DX-Forth V1.0 OK prompt. If so, congratulations, you're using a Kestrel 2DX!

Developer Build Instructions

To be refined in the future; for now, these are my cheat-sheet notes.

ROM image (only)

make bin/rom.bin

ROM Verilog Module

make rom

Cutting a New Version

tools/revise/revise patch to src/romver.h state src/romver.state macro ROMVER template 'Kestrel-2DX ROM {major}.{minor}.{patch}\r\n\n'
make rom
# rebuild FPGA image and test
fossil changes
fossil diff ...etc..
fossil commit

Substitute minor or major for patch if appropriate.

Programming the Digilent Nexys-2 Without Affecting the Flash

Using ISE WebPack 14.7 or compatible product, you should be able to execute the following instructions with minimal issues. Of course, make sure you also have installed Digilent's proprietary programming software as well.

Create your bit file from Xilinx ISE as you would normally; this will create a NEXYS2.bit file inside your ISE project directory.
Open a shell window to your project's directory containing the bit file. If your ISE project directory sits at /tmp/fossil/kestrel-2dx/ISE/kestrel-2dx, then you should be able to run cd /tmp/fossil/kestrel-2dx/ISE/kestrel-2dx.
Run sudo djtgcfg enum . On my system, the FPGA board will have the "user name" of "Nexys2"
Run sudo djtgcfg init -d Nexys2 . On my system, the FPGA is at JTAG index 0, and the flash for it on index 1.
Run sudo djtgcfg prog -d Nexys2 -i 0 -f NEXYS2.bit .

If the board is set for JTAG clocking and the project is configured to match, this will program the FPGA immediately, without affecting the flash. This is a great way to try out changes to your design without overwriting a known-good flash configuration.

¹ I do not have any MMC cards to test with; however, every available online resource describing how to use SD cards says that it should work with MMC cards as well. YMMV. I only have access to SD cards, for that's what the local grocery store sells.