Architectures/ARM/F18/GuruPlug

Guruplugs used at Seneca College to build Fedora for ARM. There are twenty Guruplugs in the Seneca build farm

Kirkwood Series

Kirkwood processors were developed for network connected consumer electronic equipment that are used in gateway/access point, set-top boxes, network storage, digital home media servers, point of services terminal, and plug computers (sheevaplug, dreamplug, guruplug, etc).

Plug Computers

A plug computer is a small form factor server, intended to provide network-based services within the home. These ARM based devices provides always-on, always-connected, and environmentally-friendly computing that is readily available for developers.

GuruPlugs

The Guruplugs are one of the popular plug computers. More information on Guruplugs can be found here. Below is the technical specifications for a typical GuruPlug Server Plus

Technical Specifications

• 1.0 Ghz - 1.2 Ghz Processor (Marvell 88F6281)
• 512 MB 16-bit DDR2 RAM
• 512 MB NAND Flash
• 802.11 b/g WiFi
• SATA 2.0 port (eSATA)
• 2 x Gigabit Ethernet
• 2 x 16550 compatible UART interfaces (external JTAG adapter)
• 2 x USB 2.0 ports
• 1 x MicroSD Slot

Running Fedora on a Kirkwood Device

This page will give a user detailed instructions for running Fedora 18 on a Kirkwood based device. The F18 image provides a user with a minimal text based installation to a serial console. At the moment there is no GUI image available. F18 image has been tested to run on GuruPlug Server Plus using microSD card and a USB thumb drive, but should also work for other devices based on the Kirkwood SOC.

Downloading the image

The first step is to download the F18 image. The prebuilt images include kernels and can be written directly to an storage medium such as an (micro)SD Card or an USB stick and requires additional steps (uboot configurations) to boot. The serial console image requires a minimum storage medium size of 4GB.

• GuruPlug Image

Writing the Image

Please be aware that writing the image to any drive (SD/microSD/USB/Hard Drive) will erase any existing data in that drive. Please make sure that the card is not write protected.

Linux Users

The image can be written to any storage device as long as it meets the minimum size requirements noted above (4GB for the serial image)

• Connect the device or card to a computer and make a note of the device file in /dev.
• To write the image to to the device run the following command (Please adjust the path in /dev)

xzcat Fedora-18-kirkwood-arm.img.xz > /dev/<location-of-storage-device>

• Once completed run the command below to ensure the entire image is written to the storage

sync

Windows Users

• Download Win32 Image Writer as well as a tool to extract the image such as 7-Zip.
• Once downloaded and installed right click on the disk image and select "7-Zip->Extract files here"
• Launch Win 32 Disk Imager and select the extracted disk image and the microSD card to write the files to. Click "Write". Be very careful during this step - all data on the selected drive will be lost!

Mac Users

• Please note that the Default Archive Utility.app will not extract the .xz file. A third party app will have to be used to decompress it. There are multiple options for that
  1. There is a Free App available in the App Store called Unarchiver.
  2. If mac homebrew or macport is already installed, then the xz utility can be downloaded and installed using one of those.
  3. The xz utils .pkg for mac can be downloaded and installed directly from xz utils
• Once the xz utility is installed, open a terminal and make a note of the current drives.

ls /dev/disk?

• Connect the microSD card to the mac and make a note of the drive.
• Open Disk Utility and make sure that the card and all the partitions in the card (if any) is unmounted
• In the terminal change to the directory where the .xz file is located
• If xz was installed from the .pkg or macport or homebrew then run the following command

xzcat Fedora-18-kirkwood-arm.img.xz > /dev/<location-of-the-microSD-card>

• If the Unarchiver app from App Store was used then just click and decompress the .xz file and then run the following (may require sudo)

dd if=Fedora-18-kirkwood-arm.img of=/dev/<location-of-the-microSD-card>

• Click and eject the microSD card

Booting the Image

Pogoplug
If you want to use Fedora on a Pogoplug, follow the Pogoplug special instructions before you continue here.

Dockstar Kernel/Initrd Addresses
To boot Fedora 18 a Dockstar you may need to use the following addresses for the kernel and the initrd, otherwise it hang loading the initrd: 0x800000 0x1100000.

Connect the newly created media to the ARM device and power on. Depending on the model/version of the plug/uboot, additional uboot parameters may be necessary or the existing ones could be edited. To do that, stop the boot process during the countdown and follow the instructions here. The Fedora 18 Kirkwood images contain an ext3 filesystem that cannot be booted directly by certain plugs (such as the GuruPlug) at this time. Please follow the appropriate installation instructions for your device.

U-Boot supporting boot from EXT partitions

The following has been tested with a GuruPlug Server Plus (remove the "saveenv" command prior to "boot" if you would only like to test without permanently changing configuration):

# NOTE: substitute "usb 1:1" with "usb 0:1" on non-Plus model devices, or try:

usb start
ext2ls usb x:1   
#where x can be any integer but usually 0-3, the right number will show a directory listing including the files uInitrd and uImage

#NOTE: If ext2ls does not work, your uboot does not support the ext2 filesystem, 
#skip down to the "U-Boot supporting boot from VFAT partitions only" section or upgrade your uboot.

printenv
set bootargs 'console=ttyS0,115200 root=LABEL=rootfs rootwait'
set loadInitrd 'ext2load usb 1:1 0x7400000 uInitrd'
set loadImage 'ext2load usb 1:1 0x6400000 uImage'
set bootcmd 'usb start; ${loadImage}; ${loadInitrd} ; bootm 0x6400000 0x7400000'
saveenv
boot

U-Boot supporting boot from VFAT partitions only

NOTE: Skip this if you have ext2 support in your uboot. You already did this in the previous step.

The first partition of the image will need to be reformatted to VFAT prior to successfully booting the device. You can do this manually if you would like, or use the livemedia-modifier tool to simplify the process. From a terminal enter the following:

wget http://fossjon.fedorapeople.org/packages/livemedia-modifier/livemedia-modifier-1.8-1.fc18.noarch.rpm
chmod 755 livemedia-modifier
./livemedia-modifier --image=<location-of-kirkwood-disk-image> --platform=kirkwood

The livemedia-modifier tool will mount the disk image, copy the contents of the boot partition to a temporary directory, reformat to VFAT and then copy the contents back to the partition.

When the reformat has completed, the following has been tested with a GuruPlug Server Plus (remove the "saveenv" command prior to "boot" if you would only like to test without permanently changing configuration):

# NOTE: substitute "usb 1:1" with "usb 0:1" on non-Plus model devices
printenv
set bootargs 'console=ttyS0,115200 root=LABEL=rootfs rootwait'
set loadInitrd 'fatload usb 1:1 0x7400000 uInitrd'
set loadImage 'fatload usb 1:1 0x6400000 uImage'
set bootcmd 'usb start; ${loadImage}; ${loadInitrd} ; bootm 0x6400000 0x7400000'
saveenv
boot

Installing the kernel to NAND

You can install the kernel and initrd directly into the Plug's NAND flash using commands similar to the following:

# NOTE: substitute "usb 1:1" with "usb 0:1" on non-Plus model devices
# NOTE: If you have ext2 support in uboot (some older versions do not), replace fatload with ext2load in the following directions. 

usb start
fatload usb 1:1 0x6400000 /uImage
nand erase 0x100000 0x400000
nand write.e 0x6400000 0x100000 0x400000
fatload usb 1:1 0x6400000 /uInitrd
nand erase 0x500000 0x1b00000
nand write.e 0x6400000 0x500000 0x1b00000
set bootargs 'console=ttyS0,115200 root=LABEL=rootfs rootwait'
set loadInitrd 'nand read.e 0x7400000 0x500000 0x1b00000'
set loadImage 'nand read.e 0x6400000 0x100000 0x400000'
set bootcmd 'nand start; ${loadImage}; ${loadInitrd} ; bootm 0x6400000
0x7400000'
saveenv
boot

Using Fedora on a Kirkwood Device

The default root password is "fedora". This should be changed immediately.

Serial Console

It is helpful to have a serial console. For the kirkwoods, you need a ttl serial/usb converter like the one on the Guruplug JTAG, a nokia serial cable, or possibly http://adafruit.com/products/954 (not tested, but it has leads so no soldering required for Pogoplug E02 or possibly Dockstars, sheevaplugs, tonidoplugs, etc?.)

The only place that sold the 1.25 pitched connectors with leads for the original guruplug jtag was someone from china off ebay. (It took 6 weeks for delivery.)

The Guruplugs and Pogoplug E02 pinouts are: http://www.plugcomputer.org/Documentation/all-categories/categoryguruplug/guruplug/#Pinouts_for_the_Guruplug_connectors

NOTE: the -connector- is different for the Pogoplug E02, (Rumor has it sometimes they are reversed pin outs.) The connector is I believe 2.54mm for the Pogoplug E02, which is the same size as an analogue cd-rom audio cable, which you can use. (You don't want the power pin).

You can use several clients to connect to your usb/serial converter. cu, picocom, screen, minicom and kermit. You need to set flow control to none. You might have to use stty commands or dig through the settings. I use kermit with these settings:

[root@daffodil ~]# cat .mykermrc
set line /dev/ttyUSB0
set speed 115200
set flow /direct-serial
set flow none
set carrier-watch off
connect
[root@daffodil ~]#

With the serial console and bootrom versions 1.21+ you can also recover a machine (bricked) that has a corrupt uboot. There are several tools available kwboot is one of those tools. It uses the uart(serial) protocol to load a uart enabled uboot image. You can use either the uart boot or the xmodem protocol which is enabled by sending a special string over uart to the machine at boot.

For bootrom versions 1.11 like on the Pogoplug pink E02's, you need a jtag adapter (buspirate or guruplug jtags have been reported to work), and openocd.

The openocd commands for the pogoplug E02 are(it is similar for all kirkwoods and should work no matter what bootrom version you have):

#init dockstar this halts the processor
dockstar_init
#initialize the nand bank #0
nand probe 0

#one of the following 2 commands:
#this command erases all of your nand on bank 0, you may not want that. it takes a couple of minutes. 
nand erase 0
--or--
#this command erases a small section of your nand on bank 0 from address 0x0 to 0x060000 instead of the whole thing.(you can)
nand erase 0 0x0 0x060000

#this loads the new u-boot.kwb image from the directory you started openocd from to the address 0x80000.
# Use full pathnames ie /home/mystuff/kwb.boot if it is in another directory. It takes a minute or two.
# (if it doesn't then you probably forgot to enable the nand.. 
load_image u-boot.kwb 0x80000
#this command writes the file to nand starting at address 0x0
nand write 0 u-boot.kwb 0 oob_softecc_kw
#this saves your changes and resets the processor. You should be able to see the new uboot on the serial console. 
reset

Note: The Guruplug jtag requires the uses of the FTDI driver, and it needs to be compiled into openocd. Fedora does NOT do that due to software licensing and distribution issues surrounding the FTDI driver. They are available from: http://www.ftdichip.com and you will have to compile the driver into your version of openocd. You may also need to make a few minor changes to the openocd configs/scripts to get it to work right with openocd 0.6.1

Known Issues

• Known release issues

Additional Support

There are Fedora ARM users all around the globe - if you need assistance, would like to provide feedback or contribute to Fedora ARM please visit us on the IRC - we can be found in #fedora-arm on Freenode. You can also contact us on the mailing list - arm@lists.fedoraproject.org