A naked Balloon board needs a number of stages of programming to make it boot Linux. The exact procedure depends on which balloon board you have, and whether it has a CPLD or FPGA. There are also several ways of actually doing things depending on your production environment and the JTAG equipment you have. Here we detail the current best practice for various boards and situations.

Normally you will have been supplied with a programmed board which can load its own new files over USB or ethernet, so can go straight on to "Uploading Newer Files", below which describes uploading a new bootloader, kernel and root filesystem. Only if you have totally new hardware do you need the full procedure, which includes uploading initial programmable logic and bootloader images over JTAG.

The whole process can be automated using the bbl utility (BalloonBinaryLoader) which will do any or all of these operations. This is the recommended way to do things but the full manual procedure is documented as well in case you need it.

The page BareMetalBuild details the process for programming a Balloon 3 board by hand without using bbl.

Balloon 3

Quick Start

Make sure your bblrc refers to the correct serial port and filenames (details on BalloonBinaryLoader), your balloon is powered and serial and JTAG are connected up (see BalloonJTAGing). (If you don't have jtag then edit bblrc to comment out OPENOCD=which openocd or remove the openocd package - you will then get manual reset prompts).

One everything is connected up do:

bbl --flash
bbl --bootldr
bbl --fpga --installer
bbl --kernel

You will be given prompts about what to do, but essentially you just have to push the reset button between each of those stages.

Then start a serial console to the balloon and hit space to get a boot prompt. Do:

boot flash

to start the NOR-based 'installer' image. Create an ext2 filesystem on the usb drive and copy debianrootfs.tgz onto it. (VFAT will appear to work but then fail in a non-obvious manner.) Plug in the USB drive and run:


and answer 'y' to the question 'install debian rootfs to nand'

The whole procedure takes about 40 minutes.

Detailed procedure

The slow version of the procedure is documented here: http://balloonboard.org/files/balloon3/distro/test-v0.1/docs/Configuring%20L3.pdf.

The upload order is different for CPLD and FPGA boards - on CPLD boards the CPLD is loaded first. On FPGA boards the FPGA is loaded after the bootloader.

So you know which you have: a CPLD board looks like this, this an FPGA one like this. (see http://balloonboard.org/gallery/index.html)

The reason for uploading the bootloader twice is that if using parallel port JTAG, loading the standard bootloader directly with bflash takes about an hour.


On power up expect ~100mA current @4V During Jtag programming @220mA. After minimal boot @380mA A balloon that has never been programmed will have the two green LEDs by the JTAG FPC connector glowing very dimly. One of these should go bright once you start jtagging.

A reset is needed between each stage to enable the new software: So after flashing the small bootloader you reset to run it. Then bbl --bootldr can load the standard bootloader. Resetting runs this, which knows how to write images to nor, so you can do bbl --fpga --installer to write those image. Then you reset again so that the fpga image gets loaded, which allows writing to NAND (the nand bus goes through the FPGA). Now you can upload the boot kernel (and rootfs if you wanted, but it's much faster over USB). Currently (test-v0.3 release, September 2007) we don't load the boot kernel over USB and have the kernel write it to NAND because the kernel and bootldr disagree slightly about YAFFS formatting, which means that kernels written by the kernel will not be booted by bootldr. This should get fixed soon.

Manual programming procedure

If you've got a setup without bbl installed, or just want to manually install software for debug purposes, these are the stages involved.

FPGA version

Balloon 2

Once you have this all installed you should be able to boot Linux - (see Balloon2GettingStarted).

Why two bootloaders?

The reason why the bootloader is put in in two stages is simply to reduce the time taken for the whole proceedure. A full build of the Bootldr bootloader is about 200K, whilst a minimal one is only about 50K. Uploading things over JTAG using a parallel port interface is _extremely_ slow (~4 mins for 50K, ~20mins for 200K) , so it makes sense to upload the smallest bootloader that will let you use the serial port, then to upload a full bootloader (that knows how to program the flash) over serial.

You could use a smaller bootloader, or a better/faster JTAG interface to speed this up but this is how things have been done so far. Improvements are welcome.

What to do - uploading newer files

The process of getting the initial bootloader and CPLD files in is covered under BalloonJTAGing, so he're we'll just cover updating the bootloader, kernel and root image, which are the normal operation for most users.

To manually update a balloon that already has a working bootloader you:

In each of the uploading options above you will then need to initiate an xmodem transfer of the appropriate file using your terminal software when prompted with "ready for xmodem download.." (ctrl-A, S on minicom, for example). If you don't start the transfer within about 20 seconds then xmodem may well fail with loads of 'NAK' complaints. If you have a failed upload you may just need to wait for the xmodem program on the balloon end to time out. It will do so after about a minute. When loading the root file system, donot unzip the file before loading, load the .gz file directly.

What to do - starting from bare metal

When you power up a new balloon2, freshly assembled, you should see a green power LED and if it hasn't had its CPLD filled yet then it will stay in reset so the RED LED will stay on too.

To do the above programming you will need a serial cable for the balloon, a JTAG programmer for the flash and a JTAG programmer for the CPLD. See BalloonJTAGing for details of JTAG hardware options. Currently these two JTAG devices are different due to the software (The CPLD programming software expects a 'wiggler'-type adaptor, the flash programming software expects a LART/JTUX-style adaptor). It would be nice to simplify this at some point.

The balloon is usually supplied with a serial cable - it may also be supplied with a combined serial/JTAG cable (as both connectors go in the same socket on the board). This is suitable for flash programming, not CPLD programming.

It is generally convenient to use all these devices via serial and parallel extension cables so you don't have to have them 6" from the back of the machine.

So the process is to plug in the serial cable, CPLD and flash JTAG adaptors, and connect the paralel cable up to the CPLD one first, then run bbl as described in BalloonBinaryLoader, which gives you prompts about when to move the parallel cable from the CPLD JTAG device to the flash JTAG device, when you need the serial cable plugged in, when to push the reset button or the return key etc.

All the above sounds complicated, and is in detail, but using the provided utilites it's actually quite painless. It generally takes about half an hour per board (with parallel port JTAG dongles): 20mins for the programming and 10 mins of faffing with wires, especially if you need to sort out powering the board first.

Balloonboard: BalloonSoftwareLoading (last edited 2012-06-10 15:03:48 by wookey)