CryoElectronicsFirmwareInstructions < CryoElectronics

---+ Building the Cryoelectronics Firmware

Building the Cryoelectronics Firmware

The cryoelectronics firmware is stored in a set of Git trees:

The base tree (ssh://kingspeak.physics.mcgill.ca/var/git/cryo_fx12/base) contains links to the other trees and some environment scripts
The hardware tree (ssh://kingspeak.physics.mcgill.ca/var/git/cryo_fx12/hardware) contains the RTL and associated files to build the hardware bitstream
The linux tree (ssh://kingspeak.physics.mcgill.ca/var/git/cryo_fx12/linux) contains a branch of Xilinx' Linux tree for the FPGA's PowerPC core
The buildroot tree (ssh://kingspeak.physics.mcgill.ca/var/git/cryo_fx12/buildroot) contains the software and development environment
The crython tree tree (ssh://kingspeak.physics.mcgill.ca/var/git/cryo_fx12/crython) contains the Python interface for the cryo board
The userspace tree (ssh://kingspeak.physics.mcgill.ca/var/git/cryo_fx12/userspace) contains user-space applications (e.g. the decimator) used on the board

To check out these trees, run the following commands:

$ git clone ssh://kingspeak.physics.mcgill.ca/var/git/cryo_fx12/base cryo
$ cd cryo
$ git submodule init
$ git submodule update

(If you get tired of entering your password, look up public-key authentication while you're waiting.)

The following material assumes the CRYO environment variable has been set to the directory containing the base git repository (i.e. $CRYO/hardware points to the hardware tree.)

Pre-requisites

You must have the following software installed:

Xilinx' ISE and EDK, version 10.1 or later
- You may need to install BerkeleyDB (BDB) 4.1. It is an older version and is not shipped with Debian or Ubuntu.

You will also need the following hardware (and properly configured drivers):

Xilinx Platform Cable USB
- See XilinxToolsHints for hints.

Preparing the Build Environment

Several steps in the following instructions require a properly configured build environment. The base tree includes an important script you need to invoke before any of the following steps:

$ cd $CRYO
$ . setenv.sh

This script should find your ISE/EDK installations and configure your shell environment accordingly.

Building the Hardware Tree

First, we generate the hardware makefile:

$ cd $CRYO/hardware/xps
$ xps -nw
XPS% xload xmp system.xmp
XPS% save make
XPS% exit

Next, we generate the bitstream:

$ make -f system.make clean
$ make -f system.make program

This hardware bitstream needs to be integrated with the bootloader software:

$ make -f system.make init_bram

At this point, you have two bitstream files in your hardware tree:

$ ls hardware/xps/implementation/*.bit
hardware/xps/implementation/download.bit
hardware/xps/implementation/system.bit

The correct file to download to the flash or FPGA over JTAG is download.bit, which has had its BRAM initialized with the bootloader code. The other, system.bit, contains hardware configuration but no bootloader software (and can safely be ignored.)

Using the Bitstream to Program the FPGA

At this point, you need to transfer the bitstream to the board. Unlike the DfMUX motherboard, there is no CompactFlash interface on this module; therefore, you need to program the on-board flash (or FPGA) using the JTAG interface.

Perform the following preparatory steps:

Turn the cryo board off (!)
Connect the JTAG pod to the board's JTAG header (J20) using the flyaway adapter.
- Note that the TDI/TDO pins are reversed on the JTAG header. If you follow the labels, you will get the correct connection; connecting pins in order (so that the JTAG pod lines up with the pin header) reverses the two.
Make sure you have drivers for the JTAG pod correctly configured and the JTAG pod is properly connected
- When the cryo board is powered off (or the JTAG pod is unplugged), the "status" LED should be amber
- When the cryo board is powered on, the "status" LED should turn green.
- If something isn't behaving, see XilinxToolsHints
Start "impact" (Xilinx' programming tool) and scan the JTAG chain
- Turn on the cryo board
- Run impact
- "Create a new project"
- "Automatically connect to a cable and identify boundary-scan chain"
- You may have to ignore some "windrvr6" warnings
- Eventually, you should see two devices in the JTAG chain: the platform flash (xcf08p) and the FPGA (xc4vfx12).
Pick one of the following options...

Option 1: Programming the FPGA (volatile)

Since the FPGA stores its bitstream in SRAM, you'll need to repeat this step each time you power up the board. Otherwise, whatever bitstream is currently stored in platform flash will be loaded by default.

Double-click on the FPGA icon (xc4vfx12)
Select the "download.bit" file you created above
Right-click on the FPGA icon (xc4vfx12)
Select "program"

Option 2: Programming the Platform Flash (non-volatile)

: Use promgen -w -p mcs -c FF -o /path/to/mcsfile -x xcf08p -ver 0 /path/to/download.bit to avoid mucking about in Impact.

Use the 'impact' tool (which ships with Xilinx' EDK/ISE) to program the flash. (Fixme: these are rough directions and should be refined.)

Select "PROM file formatter" from the box on Impact's left-hand side
Target "Xilinx PROM", MCS format; select a sensible PROM filename and directory
"I am using a Xilinx PROM in serial mode"
Select "xcf08p"; click "add"
Select the "download.bit" file you created above
Click "Generate File" from the box on Impact's left-hand side
Go back to "Boundary Scan" (on Impact's left-hand side)
Double-click on the xcf08p PROM chip in the JTAG chain
Select the MCS file you just created
Right-click on the xcf08p PROM
Select "Verify" and "Erase before programming"
Select "OK"
You will probably need to power-down and power-up the board for the new program to reach the FPGA.

Validating the burned bitstream

You should be able to connect to the tiny bootloader included in the bitstream to ensure everything until now proceeded correctly.

Find a serial-to-flyaway connector (there should be one floating around the lab.) It converts a DB-9 to a 3-pin flyaway connector.
Connect this to the board's COM1 port (J22.)
- Ground goes in the middle. To be honest, I don't remember which side is TX and which is RX; you can try both configurations (briefly) until something works.
Connect the serial cable to a PC; open a terminal program
- 115200 baud, no parity, 8 data bits, 1 stop bit
- on Linux boxes, use "screen /dev/ttyUSB0 115200" (where ttyUSB0 might have to be something else, depending on which serial hardware you're using. ttyS0/ttyS1,ttyS2/... corresponds to hardware serial ports; ttyUSB0/ttyUSB1/... correspond to USB-to-serial adapters.)
- You may have permissions problems here; you should get yourself added to the "dialout" group
Power on the board and look for a bootloader message.

Building the development environment

The entire software environment is constructed using Buildroot. This constructs a userspace environment (shell, busybox, network tools, device files, et cetera), builds the Linux kernel, and packages them together into a single image.

: Temporary steps: Make sure both source and destination files exist (i.e. you have the paths right), and run the following:

$ rm $CRYO/linux-2.6/arch/powerpc/boot/dts/fdt.dts
$ cp $CRYO/hardware/xps/ppc405_0/libsrc/wtl_standalone_v2_00_a/virtex440.dts $CRYO/linux-2.6/arch/powerpc/boot/dts/fdt.dts

The .dts file is produced by the hardware build, and describes what peripherals are present (along with their locations, interrupts, and capabilities) to the Linux kernel. Ideally, the .dts file would be linked from the hardware tree to the Linux tree, so this step would be unnecessary. For now, please do this by hand.

Now, build the software image:

$ cd $CRYO/buildroot
$ make 2>&1 | tee world.log

(The "2>&1 | tee world.log" allows you to save output generated by "make" in a file so you can dissect it later if something goes wrong.)

Problems and solutions:

If .config.cmd is missing, run "make config". Then ensure (via git diff) that your configuration has not been muddled during the process. Run git checkout HEAD .config to restore the checked-in version.
If flex or bison are not installed, run sudo apt-get install flex bison.

If this was successful, you should see the following file:

$ cd $CRYO/buildroot/binaries/uclibc
$ ls -ls rootfs.powerpc.ext2 rootfs.powerpc.tar.gz 
37836 -rw-r--r-- 1 gsmecher gsmecher 38699008 2009-09-04 17:17 rootfs.powerpc.ext2
 6492 -rw-r--r-- 1 gsmecher gsmecher  6633480 2009-09-04 17:17 rootfs.powerpc.tar.gz

These files contain the root filesystem image (they are actually redundant, since they store the same contents in different formats.) You must format a SD card using the ext2 filesystem (not the Windows-compatible FAT filesystem that is typically pre-formatted on these cards) and transfer the contents of one of these files to the flash.

Building the Linux Kernel

You must now build the Linux kernel image to use on the board. Run the following:

$ cd $CRYO/linux-2.6
$ make 2>&1 | tee world.log

Eventually, this should produce the simpleImage.fdt.elf file:

$ ls -ls arch/powerpc/boot/simpleImage.fdt.elf 
1572 -rwxr-xr-x 1 gsmecher gsmecher 1664695 2009-09-07 10:39 arch/powerpc/boot/simpleImage.fdt.elf

This file contains the Linux kernel, which must be executed on the board. This may be accomplished in two ways: either using the JTAG pod (which transfers the program to the board via USB and explicitly boots the kernel), or by storing the kernel on the Mini Module's on-board flash chip (where the bootloader may find it.)

Option 1: Using the Xilinx JTAG Pod

Connect to the "com1" serial port of your board using an RS232 cable.
Start up a terminal emulator (e.g. screen /dev/ttyUSB0 115200)
Power on your board
Configure it with the bitstream you generated previously
Connect to Ensure you get the following "hello" message:

Virtual Lab Linux Bootloader
Version: $Id: CryoElectronicsFirmwareInstructions.txt,v 1.14 2010/10/07 20:11:41 GraemeSmecher Exp $
Build: 15:55:40 Jun 16 2009
Flash memory: No kernel found.
Send Intel Hex records when ready.

We will now download the software over JTAG (ignoring the bootloader that's currently running on the board.) We could have also downloaded the software over the serial link, but serial is much slower. Note that we could also have placed the software image in flash ("Flash memory: No kernel found.") More on this later.

$ cd $CRYO/linux-2.6/arch/powerpc/boot
$ xmd
XMD% connect ppc hw
XMD% dow simpleImage.fdt.elf
XMD% run

After a short delay, the Linux bootup preamble should display on the serial terminal. You may now be interested in CryoElectronicsDriverInteraction.

Option 2: Using Linear Flash

The mini module includes 4 MB of on-board, random-access flash. This is supported by the boot loader, and mapped in Linux to a MTD (memory-type device) driver.

In order to program the flash, you need to have Linux booted up on the board (e.g. via the JTAG pod, or an older Flash-based build.) You also need a .bin file, which can be generated from the simpleImage.fdt.elf file as follows:

$ powerpc-linux-objcopy -O binary simpleImage.fdt.elf simpleImage.bin

Copy this file onto the board, either using netcat or by putting the file directly on the board's MicroSD card. Then, on the board, run:

# /usr/sbin/flashcp -v simpleImage.bin /dev/mtd0

Then, the next time you boot the board, the bootloader should recognize a Linux kernel image and boot automatically.

This topic: CryoElectronics > DigitalFMux > CryoElectronicsFirmwareInstructions Topic revision: r14 - 2010-10-07 - GraemeSmecher