Buildroot Readme for PhidgetSBC

PhidgetSBC uses buildroot to build it's root filesystem and kernel.
Our Buildroot release is based on buildroot SVN revision 24232.

Phidgets Inc. does not directly support Buildroot development.
Issues should be reported to the Buildroot community at http://buildroot.uclibc.org/

====== Building Buildroot ======

Details about using Buildroot in general should be obtained from the Buildroot website
 - http://buildroot.uclibc.org/ - this is not our product and we can't support it directly.
The website has a lot of good documentation, and the mailing list is quite useful.

We build on Debian Lenny - Ubuntu is based on Debian so it should be fine too.

To upgrade and install the GNU compiler tools on a new debian machine:
sudo apt-get update && apt-get upgrade
sudo apt-get install build-essential

The following packages are required to be installed to build the 'full' Buildroot system (install with 'sudo apt-get install'):
libncurses5-dev
bison
flex
gettext
subversion
uboot-mkimage
acl-dev
libacl1-dev
zlib1g-dev
kaffe
liblzo2-dev
texinfo

Buildroot has already been configured to build the minimal PhidgetSBC filesystem and kernel.
To build, type 'make'

This produces a .bin file in the 'binaries/' directory which can be flashed onto an SBC using the firmware upgrade configuration page.

To customize the buildroot environment, type 'make menuconfig'. This brings up a graphical interface for choosing configuration options.
The configuration data is stored in the '.config' file in the root directory.

The buildroot environment should be built from scratch before being flashed to the SBC, as incremental building can sometimes cause troubles.
This can be done by running:
make clean
./rm_root
make

You shouldn't have to deal with the .config file directly at all. If you want to reset Buildroot you could do:
make defconfig
make BOARD=phidget_sbc getconfig
make oldconfig
make

As for customizing the root filesystem, this is generally only needed if you want to add core functionality
 - like new libraries, or python, something like that. If buildroot doesn't contain what you want to add, 
you need to create a buildroot package for it - refer to the Buildroot docs. If you just want to create your own programs, 
you should work in userspace and avoid compiling the filesystem at all, except perhaps to use it's cross compiler.

Rebuild the filesystem with 'make clean', 'make'

Install the binaries produced via the PhidgetSBC web interfaces upgrade page - use either the upload file or USB drive option.

Building Buildroot can be a challenge - but it's certainly possible if you keep at it.

====== Kernel ======

The kernel patches for PhidgetSBC are located at: target/device/PhidgetSBC/kernel-patches-(kernel version)

The kernel version that is used is defined in the buildroot configuration file.

The kernel can be customised by creating a local version of the kernel source, and modifying it, 
then bringing the new patchfile back into buildroot, or simply building the kernel outside of the buildroot tree.

To create a local copy of the kernel sources, download the matching kernel version from kernel.org, then patch it (from within the kernel directory):

patch -p1 < ../linux-2.6.27.4-phidget_sbc.patch

To create a new patch for buildroot (for kernel version 2.6.27.4):

(cd linux-2.6.27.4-phidget_sbc; cp .config arch/arm/configs/phidget_sbc_defconfig)
(cd linux-2.6.27.4; make distclean)
(cd linux-2.6.27.4-phidget_sbc; make distclean)
diff -uNr linux-2.6.27.4 linux-2.6.27.4-phidget_sbc > linux-2.6.27.4-phidget_sbc.patch

Note that the .config file you want to use needs to be copied to 'arch/arm/configs/phidget_sbc_defconfig' and that 'make distclean' should be run

To build the kernel:

make phidget_sbc_defconfig
make uImage

This builds the kernel image 'uImage' in arch/arm/boot/

To customize a kernel: 'make menuconfig'

Make sure that the 'arm-linux-' cross compiler tools are avialable on your path (see cross compilation, below).

To flash this new kernel to the SBC, you either need to create a new .bin file for flashing via the web interface, 
or you could write the kernel directly to it's NAND partition using the phidgetnand command (see below).

====== Cross Compilation ======

After building buildroot, you can use it's cross compiler to build PhidgetSBC executables, including a new kernel.

This is much faster then building executables on the PhidgetSBC.

The cross compiler tools (gcc, ld, etc.) are located at: 'build_arm/staging_dir/usr/bin' - you can add this to your path, and then
compile PhidgetSBC binaries with the arm-linux- prifix to tools (ie arm-linux-gcc, arm-linux-ld, etc.)

====== PhidgetSBC .bin upgrade file format ======

The PhidgetSBC takes a .bin file as it's upgrade file. This is simply a .tar containing two files: uImage and rootfs.arm.jffs2
This .bin file is created automatically by buildroot, but you could create it yourself.

The upgrade system will overwrite both the kernel and the root filesystem.

====== phidgetnand tool ======

This tool is used for upgrading the kernel and root filesystems from the command line (via ssh).

To write a new kernel: phidgetnand write -e -p /dev/mtd3 uImage

To write a new root filesystem: phidgetnand write -e -r /dev/mtd5 rootfs.arm.jffs2

When writing a new filesystem, make sure that it's either in memory (/tmp is a good place) or on a USB drive. Use of the -r (reboot) 
option is required because once the root filesystem has bee overwritten, the system will be very unhappy until a reboot.

run phidgetnand with no options to see help.
cat /proc/mtd for a listing of all nand partitions.
