Add README.hardware

git-svn-id: https://svn.o-hand.com/repos/poky/trunk@3801 311d38ba-8fff-0310-9ca6-ca027cbcb966

1 files changed, 344 insertions, 0 deletions

diff --git a/README.hardware b/README.hardware
new file mode 100644
index 000000000..2039b19e1
--- /dev/null
+++ b/README.hardware
@@ -0,0 +1,344 @@
+                     Poky Hardware Reference Guide
+                     =============================
+
+This file gives details about using Poky with different hardware reference
+boards and consumer devices. A full list of target machines can be found by 
+looking in the meta/conf/machine/ directory. If in doubt about using Poky with 
+your hardware, consult the documentation for your board/device. To discuss 
+support for further hardware reference boards/devices please contact OpenedHand.
+
+QEMU Emulation Images (qemuarm and qemux86)
+===========================================
+
+To simplify development Poky supports building images to work with the QEMU
+emulator in system emulation mode. Two architectures are currently supported,
+ARM (via qemuarm) and x86 (via qemux86). Use of the QEMU images is covered
+in the Poky Handbook.
+
+Hardware Reference Boards
+=========================
+
+The following boards are supported by Poky:
+
+  * Compulab CM-X270 (cm-x270)
+  * Compulab EM-X270 (em-x270)
+  * FreeScale iMX31ADS (mx31ads)
+  * Marvell PXA3xx Zylonite (zylonite)
+  * Logic iMX31 Lite Kit (mx31lite)
+  * Phytec phyCORE-iMX31 (mx31phy)
+
+For more information see board's section below. The Poky MACHINE setting
+corresponding to the board is given in brackets.
+
+Consumer Devices
+================
+
+The following consumer devices are supported by Poky:
+
+  * FIC Neo1973 GTA01 smartphone (fic-gta01)
+  * HTC Universal (htcuniversal)
+  * Nokia 770/N800/N810 Internet Tablets (nokia770 and nokia800)
+  * Sharp Zaurus SL-C7x0 series (c7x0)
+  * Sharp Zaurus SL-C1000 (akita)
+  * Sharp Zaurus SL-C3x00 series (spitz)
+
+For more information see board's section below. The Poky MACHINE setting
+corresponding to the board is given in brackets.
+	
+Poky Boot CD (bootcdx86)
+========================
+
+The Poky boot CD iso images are designed as a demonstration of the Poky 
+environment and to show the versatile image formats Poky can generate. It will
+run on Pentium2 or greater PC style computers. The iso image can be 
+burnt to CD and then booted from.
+
+
+                          Hardware Reference Boards
+                          =========================
+
+Compulab CM-X270 (cm-x270)
+==========================
+
+The bootloader on this board doesn't support writing jffs2 images directly to 
+NAND and normally uses a proprietary kernel flash driver. To allow the use of
+jffs2 images, a two stage updating procedure is needed. Firstly, an initramfs
+is booted which contains mtd utilities and this is then used to write the main
+filesystem. 
+
+It is assumed the board is connected to a network where a TFTP server is 
+available and that a serial terminal is available to communicate with the 
+bootloader (38400, 8N1). If a DHCP server is available the device will use it
+to obtain an IP address. If not, run:
+
+  ARMmon > setip dhcp off
+  ARMmon > setip ip 192.168.1.203
+  ARMmon > setip mask 255.255.255.0
+
+To reflash the kernel:
+
+  ARMmon > download kernel tftp zimage 192.168.1.202
+  ARMmon > flash kernel
+
+where zimage is the name of the kernel on the TFTP server and its IP address is 
+192.168.1.202. The names of the files must be all lowercase.
+
+To reflash the initrd/initramfs:
+
+  ARMmon > download ramdisk tftp diskimage 192.168.1.202
+  ARMmon > flash ramdisk
+
+where diskimage is the name of the initramfs image (a cpio.gz file).
+
+To boot the initramfs:
+
+  ARMmon > ramdisk on
+  ARMmon > bootos "console=ttyS0,38400 rdinit=/sbin/init"
+
+To reflash the main image login to the system as user "root", then run:
+
+  # ifconfig eth0 192.168.1.203
+  # tftp -g -r mainimage 192.168.1.202
+  # flash_eraseall /dev/mtd1
+  # nandwrite /dev/mtd1 mainimage
+
+which configures the network interface with the IP address 192.168.1.203,
+downloads the "mainimage" file from the TFTP server at 192.168.1.202, erases
+the flash and then writes the new image to the flash.
+
+The main image can then be booted with:
+
+  ARMmon > bootos "console=ttyS0,38400 root=/dev/mtdblock1 rootfstype=jffs2"
+
+Note that the initramfs image is built by poky in a slightly different mode to
+normal since it uses uclibc. To generate this use a command like:
+
+IMAGE_FSTYPES=cpio.gz MACHINE=cm-x270 POKYLIBC=uclibc bitbake poky-image-minimal-mtdutils
+
+
+Compulab EM-X270 (em-x270)
+==========================
+
+FIXME
+
+
+FreeScale iMX31ADS (mx31ads)
+===========================
+
+FIXME - needs testing
+
+It is assumed a serial connection to the board is available (115200 8N1), a 
+TFTP server is available at 192.168.9.1 and the board is to be given an IP 
+address of 192.168.9.2. To set the IP address, run:
+
+  ip_address -l 192.168.9.2/24 -h 192.168.9.1
+
+To download a kernel called "zimage" from the TFTP server, run:
+
+  load -r -b 0x100000 zimage
+
+To write the kernel to flash run:
+
+  fis create kernel
+
+To download a rootfs jffs2 image "rootfs" from the TFTP server, run:
+
+  load -r -b 0x100000 rootfs
+
+To write the root filesystem  to flash run:
+
+  fis create root
+
+To load and boot a kernel and rootfs from flash:
+
+  fis load kernel
+  exec -b 0x100000 -l 0x200000 -c "noinitrd console=ttymxc0,115200 root=/dev/mtdblock2 rootfstype=jffs2 init=linuxrc ip=none”
+
+To load and boot a kernel from a TFTP server with the rootfs over NFS:
+
+  load -r -b 0x100000 zimage
+  exec -b 0x100000 -l 0x200000 -c "noinitrd console=ttymxc0,115200 root=/dev/nfs nfsroot=192.168.9.1:/mnt/nfsmx31 rw ip=192.168.9.2::192.168.9.1:255.255.255.0"
+
+
+Marvell PXA3xx Zylonite (zylonite)
+==================================
+
+These instructions assume the Zylonite is connected to a machine running a TFTP 
+server at address 192.168.123.5 and that a serial link (38400 8N1) is available 
+to access the blob bootloader. The kernel is on the TFTP server as 
+"zylonite-kernel" and the root filesystem jffs2 file is "zylonite-rootfs" and 
+the images are to be saved in NAND flash.
+
+The following commands setup blob:
+
+  blob> setip client 192.168.123.4
+  blob> setip server 192.168.123.5
+
+To flash the kernel:
+
+  blob> tftp zylonite-kernel
+  blob> nandwrite -j 0x80800000 0x60000 0x200000
+
+To flash the rootfs:
+
+  blob> tftp zylonite-rootfs
+  blob> nanderase -j 0x260000 0x5000000
+  blob> nandwrite -j 0x80800000 0x260000 <length>
+
+(where <length> is the rootfs size which will be printed by the tftp step)
+
+To boot the board:
+
+  blob> nkernel
+  blob> boot
+
+
+Logic iMX31 Lite Kit (mx31lite)
+===============================
+
+FIXME
+
+
+Phytec phyCORE-iMX31 (mx31phy)
+==============================
+
+FIXME
+
+
+                             Consumer Devices
+                             ================
+
+FIC Neo1973 GTA01 smartphone (fic-gta01)
+========================================
+
+To install Poky on a GTA01 smartphone you will need "dfu-util" tool
+which you can build with <command>bitbake dfu-util-native</command>.
+
+Flashing requires these steps:
+
+  1. Power down the device.</para>
+  2. Connect the device to the host machine via USB.
+  3. Hold AUX key and press Power key. There should be a bootmenu
+     on screen.
+  4. Run "dfu-util -l" to check if the phone is visible on the USB bus. 
+     The output should look like this:
+
+     dfu-util - (C) 2007 by OpenMoko Inc.
+     This program is Free Software and has ABSOLUTELY NO WARRANTY
+
+     Found Runtime: [0x1457:0x5119] devnum=19, cfg=0, intf=2, alt=0, name="USB Device Firmware Upgrade"
+
+  5. Flash the kernel with "dfu-util -a kernel -D uImage-2.6.21.6-moko11-r2-fic-gta01.bin"
+  6. Flash rootfs with "dfu-util -a rootfs -D <image>", where <image> is the
+     jffs2 image file to use as the root filesystem 
+     (e.g. ./tmp/deploy/images/poky-image-sato-fic-gta01.jffs2) 
+
+
+HTC Universal (htcuniversal)
+============================
+
+FIXME
+
+
+
+Nokia 770/N800/N810 Internet Tablets (nokia770 and nokia800)
+============================================================
+
+Note: Nokia tablet support is highly experimental.
+
+The Nokia internet tablet devices are OMAP based tablet formfactor devices 
+with large screens (800x480), wifi and touchscreen.
+
+To flash images to these devices you need the "flasher" utility which can be 
+downloaded from the http://tablets-dev.nokia.com/d3.php?f=flasher-3.0. This 
+utility needs to be run as root and the usb filesystem needs to be mounted 
+although most distributions will have done this for you. Once you have this 
+follow these steps:
+
+  1. Power down the device.
+  2. Connect the device to the host machine via USB 
+     (connecting power to the device doesn't hurt either).
+  3. Run "flasher -i"
+  4. Power on the device.
+  5. The program should give an indication it's found 
+     a tablet device. If not, recheck the cables, make sure you're 
+     root and usbfs/usbdevfs is mounted.
+  6. Run "flasher -r <image> -k <kernel> -f", where <image> is the
+     jffs2 image file to use as the root filesystem 
+     (e.g. ./tmp/deploy/images/poky-image-sato-nokia800.jffs2) 
+     and <kernel> is the kernel to use 
+     (e.g. ./tmp/deploy/images/zImage-nokia800.bin).
+  7. Run "flasher -R" to reboot the device.
+  8. The device should boot into Poky.
+
+The nokia800 images and kernel will run on both the N800 and N810.
+
+
+Sharp Zaurus SL-C7x0 series (c7x0)
+==================================
+
+The Sharp Zaurus c7x0 series (SL-C700, SL-C750, SL-C760, SL-C860, SL-7500)
+are PXA255 based handheld PDAs with VGA screens. To install Poky images on
+these devices follow these steps:
+
+  1. Obtain an SD/MMC or CF card with a vfat or ext2 filesystem.
+  2. Copy a jffs2 image file (e.g. poky-image-sato-c7x0.jffs2) onto the
+     card as "initrd.bin":
+
+     $ cp ./tmp/deploy/images/poky-image-sato-c7x0.jffs2 /path/to/my-cf-card/initrd.bin
+
+  3. Copy an Linux kernel file (zImage-c7x0.bin) onto the card as 
+     "zImage.bin":
+
+     $ cp ./tmp/deploy/images/zImage-c7x0.bin /path/to/my-cf-card/zImage.bin
+
+  4. Copy an updater script (updater.sh.c7x0) onto the card
+     as "updater.sh":
+
+     $ cp ./tmp/deploy/images/updater.sh.c7x0 /path/to/my-cf-card/updater.sh
+
+  5. Power down the Zaurus.
+  6. Hold "OK" key and power on the device. An update menu should appear 
+     (in Japanese).
+  7. Choose "Update" (item 4).
+  8. The next screen will ask for the source, choose the appropriate 
+     card (CF or SD).
+  9. Make sure AC power is connected.
+  10. The next screen asks for confirmation, choose "Yes" (the left button).
+  11. The update process will start, flash the files on the card onto 
+      the device and the device will then reboot into Poky.
+
+
+Sharp Zaurus SL-C1000 (akita)
+=============================
+
+The Sharp Zaurus SL-C1000 is a PXA270 based device otherwise similar to the 
+c7x0. To install Poky images on this device follow the instructions for 
+the c7x0 but replace "c7x0" with "akita" where appropriate.
+
+
+Sharp Zaurus SL-C3x00 series (spitz)
+====================================
+
+The Sharp Zaurus SL-C3x00 devices are PXA270 based devices similar
+to akita but with an internal microdrive. The installation procedure 
+assumes a standard microdrive based device where the root (first) 
+partition has been enlarged to fit the image (at least 100MB, 
+400MB for the SDK).
+
+The procedure is the same as for the c7x0 and akita models with the 
+following differences:
+
+ 1. Instead of a jffs2 image you need to copy a compressed tarball of the 
+    root fileystem (e.g. poky-image-sato-spitz.tar.gz) onto the
+    card as "hdimage1.tgz":
+
+    $ cp ./tmp/deploy/images/poky-image-sato-spitz.tar.gz /path/to/my-cf-card/hdimage1.tgz
+
+ 2. You additionally need to copy a special tar utility  (gnu-tar) onto 
+    the card as "gnu-tar":
+
+    $ cp ./tmp/deploy/images/gnu-tar /path/to/my-cf-card/gnu-tar
+
+
+