D 2018-03-03T07:03:03.489
L Building
N text/x-markdown
P ef29fa2226a0cd917703d8dd9fd1e79db4aa526a
U kc5tja
W 10483
# 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](#quick)
instructions.
However,
if you want to customize the design
or otherwise contribute to its development,
then you'll want to follow the
[Developers Build](#dev)
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.
## <a name="quick">Quick Build Instructions</a>
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.
1. Download the SD/MMC card image [`kestrel-2dx-forth.img`](uv/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.
1. Insert a blank SD/MMC<sup>[1](#sd)</sup> 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.
1. 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.
1. 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).
1. 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.
1. Download the [`kestrel-2dx-nexys2-jtag.bit`](uv/kestrel-2dx-nexys2-jtag.bit) file.
1. On your Digilent Nexys-2 board, make sure that jumper JP9 is set to `JTAG`.
1. Run `djtgcfg enum` . On my system, the FPGA board will have the "user name" of "Nexys2".
1. Run `djtgcfg init -d Nexys2`. On my system, the FPGA is at JTAG index 0.
1. Run `djtgcfg prog -d Nexys2 -i 0 -f NEXYS2.bit` (assuming your JTAG is also at index 0). Use `-i 1` if for some reason your FPGA appears at index 1.
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
**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.
1. Download the SD/MMC card image [`kestrel-2dx-forth.img`](uv/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.
1. Insert a blank SD/MMC<sup>[1](#sd)</sup> 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.
1. 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.
1. 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).
1. 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.
1. Download the [`kestrel-2dx-nexys2-rom.bit`](uv/kestrel-2dx-nexys2-rom.bit) file.
1. On your Digilent Nexys-2 board, make sure that jumper JP9 is set to `ROM`.
1. Run `djtgcfg enum` . On my system, the FPGA board will have the "user name" of "Nexys2".
1. Run `djtgcfg init -d Nexys2`. On my system, the flash ROM is at JTAG index 1.
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.
1. 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!
## <a name="dev">Developer Build Instructions</a>
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.
1. Create your bit file from Xilinx ISE as you would normally; this will create a `NEXYS2.bit` file inside your ISE project directory.
2. 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`.
3. Run `sudo djtgcfg enum` . On my system, the FPGA board will have the "user name" of "Nexys2"
4. Run `sudo djtgcfg init -d Nexys2` . On my system, the FPGA is at JTAG index 0, and the flash for it on index 1.
5. 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.
<hr />
<sup><a name="sd">1</a></sup> 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.
Z 63ea7e9a62b7f10cbad494661f318ffe