SheevaPlug Installer
The SheevaPlug installer is a new software package intended to replace the current recovery tool for reinstalling or reviving a bricked plug.
The main new features in the installer are -
- Generic that can be used to install any distro (or any operating system even).
- Distro specific stuff is under a directory called 'installer'.
- Built-in openocd that automatically flashes uboot.
Missing features -
- GUI
- Some restructuring of the files to make it more scalable?
CAUTION: Newer GlobalScale (2010) plugs are shipping with a faster processor than original. Using this installer will 'brick' your plug. You have to upgrade to kernel 2.6.36 or later, EXCEPT that this kernel does not fit inside the default partition. The procedure for installation is in need of updating.
As of December 2010, GlobalScale was shipping SheevaPlugs into the U.S. with the 1.2 GHz processor. Furthermore, the note about the partition sizes only relates to an error introduced by following the "USB Flash Recovery" document. The newer installer script should correct that. But, if worried, check your U-Boot variables, you should see in your Plug's mtdpartitions a section similar to 0x400000@0x100000(uImage). 0x400000 is 4 MB, the size needed. If you see 0x300000 in your variables (anywhere) that must be corrected.
Here is a step by step guide that works (only if your OpenOCD connection will work): http://plugcomputer.org/plugforum/index.php?topic=3680.0
In any case, you may also wish to read this page for other information.
Release version 1.0
What are the changes from alpha-6?
Changes are -
- Supports both Linux and Windows (works on XP) host OS
- Supports loading root filesystem to either internal NAND flash or external SD card
- Based on Kernel 2.6.30.2 (thanks cbxbiker61)
- Includes latest uboot (version 3.4.19) -
- Better SD card support
- Better FAT32 USB partitions
- Improved internal NAND interface timing (faster access)
- Based on OpenOCD release 2.0
- Includes sources of initrd, uboot-envtool
How to install 1.0 ?
Following instructions are for installing Ubuntu 9.04.
- Download the tarball from here
- Untar the archive onto the host that is connected to the plug by the USB serial cable
- Carefully read the README.txt file and follow the instructions. In brief -
- Copy the content of the 'installer' directory into the root directory of an empty FAT32 formatted USB stick
- Insert the USB stick into the plug's USB port
- Make sure you read the bugs section in the README.txt - especially for the minicom console users
- IMPORTANT NOTE FOR NEWER PLUGS (> 7/30/09ish)
- Power your sheevaplug
- On Linux host run 'sudo php /runme.php'
- On Windows host run 'runme.exe nand|mmc' from the command prompt. Afterwards the Windows version beeps; you need to unplug your mini usb cable, plug it back again and open the terminal (See How-to setup PuTTY for the SheevaPlug on Windows).
- On Linux you can launch serial terminal console in the beginning of the process. putty is known to work well.
- Wait for two minutes until fresh new U-Boot is up and running.
- Don't stop U-Boot count down. Wait for additional 5 minutes until it reflashes itself from the USB stick.
- If U-Boot was stopped (sometimes because of opening a terminal on Windows) you can restart it by running 'run recover1' on the U-boot command line.
Troubleshooting
Cannot connect to plug on Windows
On Windows host, if runme.exe cannot connect to the SheevaPlug, make sure you have installed LibUSB filter driver and used the helper utility that came with it to install the filter to USB serial device. There are three USB devices, and installing filter driver to the "vid:9e88 pid:9e8f rev:0500 USB composite device" helped at least for me.
See [1].
- First make sure that libftdi is installed. If you're on Ubuntu, use Synaptic Package Manager or sudo apt-get install libftdi1
- It may be due to interacting with the plug via usb-serial before the installer script gets a chance to do so, so try again without opening any screens or putty sessions to the plug. After the installer has finished, you should have no problem connecting to the plug via usb-serial.
You are on an 64-bit OS, and the pre-compiled openocd provided in the tarball is for a 32-bit OS, and thus requires a 32-bit version of libftdi.so.1. You have a 64-bit version of libftdi.so.1 installed. To resolve this, replace the provided openocd with a 64-bit one to match your libftdi.
(1) Either install openocd from your distribution's package manager ('apt-get install openocd' on Ubuntu/Debian) or manually compile it by follow the instructions at [2], stopping after building openocd.
(2) Move to the openocd directory in the installer tree
[user@localhost ~] $ cd path/to/sheevaplug-installer-v1.0/uboot/openocd/
(3) Rename the pre-compiled, 32bit openocd so it's out of the way.
[user@localhost openocd] $ mv openocd openocd32
(4) Symlink to the 64bit openocd you just compiled (first command) or the one you installed from the package (second command)
[user@localhost openocd] $ ln -s ../../../path/to/openocd-0.2.0/src/openocd [user@localhost openocd] $ ln -s `which openocd`
"You must run this as root" when you are root
If you get:
root@computer:sheevaplug-installer-v1.0# php runme.php nand PHP Notice: Undefined index: OS in /home/igibbs/downloads/linux/plug/sheevaplug-installer-v1.0/runme.php on line 7 PHP Notice: Undefined index: USER in /home/igibbs/downloads/linux/plug/sheevaplug-installer-v1.0/runme.php on line 43 You must run this as root
even though you are root, it's because the script checks the PHP variable $_ENV["USER"] to see who you are. On some PHP installations (such as Ubuntu), PHP may be configured to not use system environment variables to populate this variable, so the variable ends up blank (hence undefined). In order for this variable to be set, the PHP core directive variables_order must include the letter E. See here for more detail. To correct:
- Open php.ini (/etc/php5/cli/php.ini/ on Ubuntu)
- Find variables_order
- Make sure its value includes E, such as EGPCS
EGPCS is the default value, so simply commenting out any value that is set should also work.
"Error: No valid NAND flash driver found (0)" then "openocd FAILED"
This is because the file sheevaplug-installer-v1.0/uboot/openocd/config/board/sheevaplug.cfg is duff (see [3]. Replace it with this one [4]
"Error: timed out while waiting for target halted" then "openocd FAILED"
This is because the plug is up and running whatever OS is on it, and therefore doesn't respond to the shutdown command sent by openocd. Reset it and interrupt the boot process so that it drops into the Marvell >>> prompt.
"erased blocks 0 to 5 on NAND flash device #0 'NAND 512MiB 3,3V 8-bit'" then "openocd FAILED"
It probably hasn't failed. Open the serial port connection and watch what's going on. If it got as far as erasing the NAND, the rebuild process is probably now happening.
Previous Alpha-6 Release
What's included in the alpha-6 release
The alpha-6 includes the following -
- uboot that supports FAT32 and SD card support (*). Please refer to the forums post here - Thanks kwonsk
- Linux kernel 2.6.30-rc#6 and it's modules from here - Thanks cbxbiker61
- Ubuntu 9.04 root filesystem - Refer to the script inside 'installer' directory to see how to recreate this rootfs.
- Switch from JFFS2 to the newer and faster booting UBIFS file system.
(*) This is NOT official Marvell support. The SD card support in this Uboot is partial and known to be buggy. Marvell is working on official SD card support, details in the future.
In this wiki, the installer is for installing the Ubuntu 9.04 from an image. Hopefully the community will like this installer and build their own 'installer' directories that provides other distros.
How to install alpha-6 ?
Following instructions are for installing Ubuntu 9.04.
- Download the tarball from here
- Untar the archive onto the Linux host that is connected to the plug by the USB serial cable
- Carefully read the README.txt file and follow the instructions. In brief -
- Copy the content of the 'installer' directory into the root directory of an empty FAT32 formatted USB stick
- Insert the USB stick into the plug's USB port
- Make sure you read the bugs section in the README.txt - especially for the minicom console users
- Power your sheevaplug
- IMPORTANT NOTE FOR NEWER PLUGS (7/30/09ish)- see extended note below...
- Run 'sudo ./runme.sh' from the Linux host connected to the plug
- You can launch serial terminal console in the beginning of the process. putty is known to work well.
- Wait for two minutes until fresh new U-Boot is up and running.
- Don't stop U-Boot count down. Wait for additional 5 minutes until it reflashes itself from the USB stick.
Important Note for Newer Plugs (7/30/09ish)
If you are getting errors when trying to connect to the plug, you may need to change the Vendor and Product IDs in the config (sheevaplug-installer-v1.x\uboot\openocd\config\interface\sheevaplug.cfg ). This is needed if you see the ftdi device and messages as outlined above, but have errors when trying to connect using the runme.sh. You need to change the file so that it contains:
interface ft2232 ft2232_layout sheevaplug ft2232_vid_pid 0x1c0c 0x0102 jtag_khz 2000 #ft2232_vid_pid 0x9e88 0x9e8f #ft2232_device_desc "SheevaPlug JTAGKey FT2232D B"
NOTE: Since at least 2010-12, Some (all?) of the GlobalScale Sheevas shipped in the U.S. are using VID/PID 0x9e88 0x9e8f, so this file does not need to change.
Why reinventing the wheel ?
The original recovery tool has big limitation that it doesn't reflash u-boot, which is important for a seriously bricked plug.
We started from that, and given that the tool itself isn't easy to master and to scale to other distros, we decided to re-invent the wheel.
What are the internals ?
The runme.sh script does the following -
- Creates a uboot-env.bin 128KB file which will have the uboot environment variables.
- Populate uboot-env.bin with default environment variables (refer to the scripts-linux/uboot-env/uboot-dflt.txt file).
- Reads the installer/uboot-custom.txt and change uboot-env.bin accordingly
- Start openocd (static binary) that -
- Initialize the plug
- Erase blocks 5-6 on the plug's NAND flash and write to it uboot-env.bin
- Erase blocks 0-4 on the plug's NAND flash and writes uboot/uboot.bin
- Releases the processor to start booting from a fresh new uboot.
After that the plug starts executing its bootcmd. In the alpha-6 example, first time bootcmd is configured as follows -
bootcmd = run recover1
and recover1 is -
recover1 = setenv mainlineLinux yes; setenv arcNumber 2097; setenv bootcmd run recover2; saveenv; reset
So, basically recover1 sets some env variables, sets bootcmd to run recover2 (for next reset), saves the env and resets the plug.
In the next reset bootcmd will have the following -
bootcmd = run recover2
Refer to the installer/uboot-custom.txt file in the alpha-6 release to see all uboot command sequencing being used.
How can I modify it to install my ...
Please read the README.txt file for suggestions.
Then read the README.txt inside the 'installer' directory for explanation about the usage of files.
How can I modify it to install open u-boot ...
Please apply the patch File:Patch Update-Sheevaplug-installer-for-open-u-boot.tar.gz to the SheevaPlug installer root folder
Build open u-boot for SheevaPlug since it it not included in this package, please refer Das U-boot plug support
Replace u-boot.bin with u-boot.kwb (flashable open u-boot binary), Medical Transcription
Follow the process explained in the above chapter
