Getting Started with ROACH2

From Casper
Jump to navigationJump to search

Your ROACH2 boards ship with all devices already programmed. However, there are some aspects of the device you may wish to customise before deployment.

Familiarise with ROACH2

Shipping Defaults

ROACH2 ships with the FLASH memory containing uBoot (a simple bootloader including some ROACH-specific commands), a standard Linux kernel for the PowerPC, tcpborphserver3(control server that speaks KATCP and uses memory mapped device driver to handle FPGA transactions) and a stripped-down Linux root filesystem called Busybox.

The MAC address of the PowerPC 1GbE port can be changed in uBoot with the command setenv ethaddr xx:xx:xx:xx:xx:xx. Any changes are volatile and requires a saveenv command to store them on flash.

Front Panel

Error creating thumbnail: Unable to save thumbnail to destination
  • Power: Pushbutton that powers on/off the board.
  • Reset: Pushbutton that resets the board.
  • fault : red led. On indicates a warning threshold has been exceeded (thermal fan or temperature or voltage)
  • cpu ready: green led. Flickering indicates PowerPC is processing commands, stays ON when PowerPC is idle.

NOTE: tcpborphserver3 turns off this LED while processing a katcp command (and when done turns it on again) - this is an attempt at an activity LED - This logic is implemented using the linux input event framework(drivers/input/misc/r2chassis.c).

  • cpu error: red led.
  • fpga leds(0-7). user programmable GPIOs.

The boot procedure

You can watch the boot procedure by connecting a serial port configured for 115200,N,8 to ttyUSB2.

The PowerPC loads uBoot, checks memory and network. Unless you press a key to interrupt the boot process (over the serial port), it will load Linux. The kernel's default boot parameters will load Busybox from flash. With no additional hardware, you can use Busybox by logging in as "root", with no password.

The boot options


Booting from onboard FLASH memory. This default option offers a fully functional tcpborphserver3 interface out-of-the-box. soloboot file system mounts read only. You can upload your boffile from your control computer through KATCP using the "upload" KATCP command.


Booting from NFS mounted file system. All files required to boot ROACH2 using NFS, u-boot, kernel and on-board file system can be obtained from Follow the instructions on the README file found there. Copy your boffiles into the ROACH2 file systems /boffiles directory. KATCP looks in this directory and lists it when using the ?listbof command. Alternatively KATCP provides an "upload" command that can be used to upload a boffile to the FPGA from your control computer.

mmcboot and usbboot

ROACH2 has sufficient onboard flash to keep a number of (optionally compressed) boffiles there without having to use external storage. So development work on mmc and usbboot(issues with usb also) is halted for now.

Flash system layout

The FLASH size in ROACH2 is 128M. The layout is as follows:

       •     Linux Kernel:            0x00000000 -> 0x003fffff   (4MB), the on-board Linux Kernel
       •     Linux Filesystem:        0x00400000 -> 0x043fffff  (64MB), contains on-board filesystem for Linux OS
       •     User Filesystem:         0x04400000 -> 0x073fffff  (48MB), contains a RW filesystem for UBoot and Linux
       •     BIST Filesystem:         0x07400000 -> 0x07efffff  (11MB), contains self-test bitstreams (boffiles)
       •     Reserved 1:              0x07f00000 -> 0x07f3ffff (256KB), reserved for future use
       •     UBoot Environment:       0x07f40000 -> 0x07f7ffff (256KB), contains UBoot's environment
       •     UBoot :                  0x07f80000 -> 0x07ffffff (512KB), contains UBoot

i2c EEPROM layout

i2c EEPROM at address 0x54(first 256B page). The layout is as follows:

  • 0x00 - 0x0F (16B) Boot config H uses first 16 bytes.
  • 0x10 - 0x14 (5B) Serial number in binary form [manufacturer code(0x10): roach version(0x11): revision no(0x12): batch no(0x13): board no within batch(0x14)]

uboot derives a default locally administered MAC address from the serial number stored in EEPROM. uboot only computes a locally administered MAC address if none has been set in flash. If you have a purchased / globally administered MAC address, you would store that in flash and uboot uses it as the MAC address.

ROACH2 serial number scheme

The serial number is 5 characters long and in this format (these are 8-bit characters): Manufacturer, type, revision, batch, board

  • Manufacturer: Each manufacturer will have a letter assigned, this value is then the ASCII code for that letter. Digicom is D or 68 (44 hex) in ASCII.
  • Type: This is the type of ROACH, ROACH1 = 0 and ROACH2 = 1, etc. for following versions.
  • Revision: Board revision
  • Batch: Build batch (256 batches possible)
  • Board: Board number in the batch (256 boards per batch possible).

So the 9'th board in production run 6 by Digicom for ROACH2, revision 2 boards will have the following serial number:44:01:02:06:09 or may be printed as D01020609.

We derive default MAC addresses from this serial number by adding 02 to the front, so the MAC address for the example above is: 02:44:01:02:06:09 Please note that these are only to be used on internal networks, if a ROACH board is to be used "in the wild" a proper MAC address must be acquired.


The list of available sensors in ROACH2 can be obtained by issuing the following commands in telnet.

  • ?sensor-list

?sensor-list gives you a description of each sensor, including the units.

To read a sensor value use the katcp command in the format ?sensor-sampling sensor-name example: To monitor the PPC temperature the following sensor is read

  • ?sensor-sampling raw.temp.ppc period 2000

Sample output of above command that monitors PPC temperature:

  • #sensor-status 539134 1 raw-temp-ppc nominal 41000

NOTE: Here 41000 is in millidegrees Celsius - so the temperature of your processor is 41degC.

To make it stop sampling the sensor

  • ?sensor-sampling raw.temp.ppc none OR just disconnect from the telnet session.

ROACH2 kernel, bootloader and romfs upgrades

Grab the files here (NOTE: The nfs tarball must be untarred as root for correct permissions):

To program the new u-boot

(NB! choose the correct binary for your revision of R2, programming the wrong binary will cause the board to switch itself off at boot, and fixing that requires soldering on the board):

  • Set up a tftp and dhcp server (see the tftp section in the test machine setup instructions).
  • Create a symlink or rename the u-boot binary to "u-boot.bin" e.g. "ln -s u-boot-r2-rev1.bin u-boot.bin" in the tftp directory.
  • Plug a USB cable into the ROACH2 and open a terminal session to ttyUSB2 (Minicom is good, see the document above for setting up a minicom session to connect to ttyUSB2)
  • NB! Do not skip this step: The u-boot macro to reprogram u-boot is incorrect, you must define a new one (once the new u-boot is flashed the macro will be correct). Using the current macro bricks the board (can be recovered by reprogram u-boot via setting up a test machine and sending a xmodem receiver to the PPC via JTAG and then sending the binary)
    • Boot into u-boot (reset the board and press any key to stop autoboot)
    • type: "setenv writeuboot protect off 0xfff80000 0xffffffff\; era 0xfff80000 0xffffffff\; cp.b 0x4000000 0xfff80000 \$\{filesize\}" at the u-boot prompt without the quotes. Note this is the same as the current macro but the current cp.b 0x400000 is missing a 0! Leave the protect on bit, the U-boot command line is too short to add it and the macro will be overwritten anyway when the new u-boot loads.
    • type: "printenv" and double check the macro!
  • type: "run tftpuboot"
  • when done type: "reset". You should see u-boot loading and *** Warning - bad CRC, using default environment. All the macros are reset to defaults.

To program the kernel:

  • Create a symlink or rename the kernel image to uImage e.g. "ln -s uImage-r2borph3 uImage" in the tftp directory.
  • At the uboot prompt type: run tftpkernel
  • Note that all the fixes has been for tcpborphserver3 and to use that you have to flash the borph3 kernel. To use tcpborphserver2 flash the borph2 kernel.

To program the new romfs:

N.B: the current romfs is mainly busybox (unmodified) and the katcp tools (tcpborphserver3) and then some libraries and extra utilities.

  • Create a symlink or rename the romfs image to romfs e.g. "ln -s roach2-root-2012-10-18.romfs romfs" in the tftp directory.
  • At the uboot prompt type: run tftproot
  • This takes a long time! About 5 minutes.

Software sources

How Tos

How to set a static IP address in ROACH2

edit file with static ip address, also uncomment telnetd for telnet.

  • vi /usr/rc.local
  • ifconfig eth0 x.x.x.x netmask

How to erase the user file system if flash becomes corrupt?

  • era 0xfc400000 0xfff3ffff
  • cp.b 0x4000000 0xfc400000 ${filesize}

NOTE: Assuming your user file system is copied to 0x4000000

How to run katcp commands without using telnet?

  • use kcpcmd utility.

eg: To program a foo.bof file

    • kcpcmd progdev foo.bof
  • use a script and invoke kcpcmd like any other utility. Shell example (-p allows more interesting constructs)

    • #!/bin/sh
    • if kcpcmd -i -s $ROACHNAME wordread sys_scratchpad 0 | grep -q deadbeef ; then
    • echo "scratchpad already set to to deadbeef"
    • exit 0
    • else
    • kcpcmd -i -s $ROACHNAME wordwrite sys_scratchpad 0 0xc0cac01a
    • fi

How to netboot ROACH and ROACH2s on same network?(Ack David Macmahon)

Here's yet another example of using dnsmasq to boot both ROACH1s and ROACH2s.

In addition to the "usual" dnsmasq configuration details, you'll need to add/modify the following lines to match your setup:

How to differentiate between roach1 and roach2

  • dhcp-mac=roach1,02:*:00:*:*:*
  • dhcp-mac=roach2,02:*:01:*:*:*

Send different root filesystem paths for roach1 and roach2

  • dhcp-option=net:roach1,option:root-path,
  • dhcp-option=net:roach2,option:root-path,

Send different boot image info for roach1 and roach2

  • dhcp-boot=net:roach1,uboot-roach1/uImage
  • dhcp-boot=net:roach2,uboot-roach2/uImage-r2borph3

How to change root password in ROACH2?

  • $busybox passwd

NOTE: to change the root password from just a carriage return to your choice

How to remote log katcp messages?

To log kernel level messages enable remote logging with syslog utility.

To log katcp messages:

  • Check out
  • Remove/comment out KATCP_STRICT_CONFORMANCE in
  • Compile on your logging server, not the roach.
  • Use the utility log/kcplog to connect to a remote roach and save katcp log messages to local file. kcplog understands SIGHUP and thus can be used under logrotate, while SIGUSR? can be used to de/increase the log verbosity.

Use ./kcplog -h for more information.

You can also monitor individual hardware sensors with commands like this

  • (echo "?sensor-sampling raw.voltage.3v3 event" ; cat ) | nc roach_host 7147

How do I soft-reboot the board?

  • From uBoot: restart
  • From Busybox: busybox reboot -f
  • From supplied Linux: reboot or shutdown -r now