README.hardware

   1                      Poky Hardware Reference Guide
   2                      =============================
   3
   4 This file gives details about using Poky with different hardware reference
   5 boards and consumer devices. A full list of target machines can be found by
   6 looking in the meta/conf/machine/ directory. If in doubt about using Poky with
   7 your hardware, consult the documentation for your board/device. To discuss
   8 support for further hardware reference boards/devices please contact OpenedHand.
   9
  10 QEMU Emulation Images (qemuarm and qemux86)
  11 ===========================================
  12
  13 To simplify development Poky supports building images to work with the QEMU
  14 emulator in system emulation mode. Two architectures are currently supported,
  15 ARM (via qemuarm) and x86 (via qemux86). Use of the QEMU images is covered
  16 in the Poky Handbook.
  17
  18 Hardware Reference Boards
  19 =========================
  20
  21 The following boards are supported by Poky:
  22
  23   * Compulab CM-X270 (cm-x270)
  24   * Compulab EM-X270 (em-x270)
  25   * FreeScale iMX31ADS (mx31ads)
  26   * Marvell PXA3xx Zylonite (zylonite)
  27   * Logic iMX31 Lite Kit (mx31lite)
  28   * Phytec phyCORE-iMX31 (mx31phy)
  29
  30 For more information see board's section below. The Poky MACHINE setting
  31 corresponding to the board is given in brackets.
  32
  33 Consumer Devices
  34 ================
  35
  36 The following consumer devices are supported by Poky:
  37
  38   * FIC Neo1973 GTA01 smartphone (fic-gta01)
  39   * HTC Universal (htcuniversal)
  40   * Nokia 770/N800/N810 Internet Tablets (nokia770 and nokia800)
  41   * Sharp Zaurus SL-C7x0 series (c7x0)
  42   * Sharp Zaurus SL-C1000 (akita)
  43   * Sharp Zaurus SL-C3x00 series (spitz)
  44
  45 For more information see board's section below. The Poky MACHINE setting
  46 corresponding to the board is given in brackets.
  47
  48 Poky Boot CD (bootcdx86)
  49 ========================
  50
  51 The Poky boot CD iso images are designed as a demonstration of the Poky
  52 environment and to show the versatile image formats Poky can generate. It will
  53 run on Pentium2 or greater PC style computers. The iso image can be
  54 burnt to CD and then booted from.
  55
  56
  57                           Hardware Reference Boards
  58                           =========================
  59
  60 Compulab CM-X270 (cm-x270)
  61 ==========================
  62
  63 The bootloader on this board doesn't support writing jffs2 images directly to
  64 NAND and normally uses a proprietary kernel flash driver. To allow the use of
  65 jffs2 images, a two stage updating procedure is needed. Firstly, an initramfs
  66 is booted which contains mtd utilities and this is then used to write the main
  67 filesystem.
  68
  69 It is assumed the board is connected to a network where a TFTP server is
  70 available and that a serial terminal is available to communicate with the
  71 bootloader (38400, 8N1). If a DHCP server is available the device will use it
  72 to obtain an IP address. If not, run:
  73
  74   ARMmon > setip dhcp off
  75   ARMmon > setip ip 192.168.1.203
  76   ARMmon > setip mask 255.255.255.0
  77
  78 To reflash the kernel:
  79
  80   ARMmon > download kernel tftp zimage 192.168.1.202
  81   ARMmon > flash kernel
  82
  83 where zimage is the name of the kernel on the TFTP server and its IP address is
  84 192.168.1.202. The names of the files must be all lowercase.
  85
  86 To reflash the initrd/initramfs:
  87
  88   ARMmon > download ramdisk tftp diskimage 192.168.1.202
  89   ARMmon > flash ramdisk
  90
  91 where diskimage is the name of the initramfs image (a cpio.gz file).
  92
  93 To boot the initramfs:
  94
  95   ARMmon > ramdisk on
  96   ARMmon > bootos "console=ttyS0,38400 rdinit=/sbin/init"
  97
  98 To reflash the main image login to the system as user "root", then run:
  99
 100   # ifconfig eth0 192.168.1.203
 101   # tftp -g -r mainimage 192.168.1.202
 102   # flash_eraseall /dev/mtd1
 103   # nandwrite /dev/mtd1 mainimage
 104
 105 which configures the network interface with the IP address 192.168.1.203,
 106 downloads the "mainimage" file from the TFTP server at 192.168.1.202, erases
 107 the flash and then writes the new image to the flash.
 108
 109 The main image can then be booted with:
 110
 111   ARMmon > bootos "console=ttyS0,38400 root=/dev/mtdblock1 rootfstype=jffs2"
 112
 113 Note that the initramfs image is built by poky in a slightly different mode to
 114 normal since it uses uclibc. To generate this use a command like:
 115
 116 IMAGE_FSTYPES=cpio.gz MACHINE=cm-x270 POKYLIBC=uclibc bitbake poky-image-minimal-mtdutils
 117
 118
 119 Compulab EM-X270 (em-x270)
 120 ==========================
 121
 122 FIXME
 123
 124
 125 FreeScale iMX31ADS (mx31ads)
 126 ===========================
 127
 128 FIXME - needs testing
 129
 130 It is assumed a serial connection to the board is available (115200 8N1), a
 131 TFTP server is available at 192.168.9.1 and the board is to be given an IP
 132 address of 192.168.9.2. To set the IP address, run:
 133
 134   ip_address -l 192.168.9.2/24 -h 192.168.9.1
 135
 136 To download a kernel called "zimage" from the TFTP server, run:
 137
 138   load -r -b 0x100000 zimage
 139
 140 To write the kernel to flash run:
 141
 142   fis create kernel
 143
 144 To download a rootfs jffs2 image "rootfs" from the TFTP server, run:
 145
 146   load -r -b 0x100000 rootfs
 147
 148 To write the root filesystem  to flash run:
 149
 150   fis create root
 151
 152 To load and boot a kernel and rootfs from flash:
 153
 154   fis load kernel
 155   exec -b 0x100000 -l 0x200000 -c "noinitrd console=ttymxc0,115200 root=/dev/mtdblock2 rootfstype=jffs2 init=linuxrc ip=none”
 156
 157 To load and boot a kernel from a TFTP server with the rootfs over NFS:
 158
 159   load -r -b 0x100000 zimage
 160   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"
 161
 162
 163 Marvell PXA3xx Zylonite (zylonite)
 164 ==================================
 165
 166 These instructions assume the Zylonite is connected to a machine running a TFTP
 167 server at address 192.168.123.5 and that a serial link (38400 8N1) is available
 168 to access the blob bootloader. The kernel is on the TFTP server as
 169 "zylonite-kernel" and the root filesystem jffs2 file is "zylonite-rootfs" and
 170 the images are to be saved in NAND flash.
 171
 172 The following commands setup blob:
 173
 174   blob> setip client 192.168.123.4
 175   blob> setip server 192.168.123.5
 176
 177 To flash the kernel:
 178
 179   blob> tftp zylonite-kernel
 180   blob> nandwrite -j 0x80800000 0x60000 0x200000
 181
 182 To flash the rootfs:
 183
 184   blob> tftp zylonite-rootfs
 185   blob> nanderase -j 0x260000 0x5000000
 186   blob> nandwrite -j 0x80800000 0x260000 <length>
 187
 188 (where <length> is the rootfs size which will be printed by the tftp step)
 189
 190 To boot the board:
 191
 192   blob> nkernel
 193   blob> boot
 194
 195
 196 Logic iMX31 Lite Kit (mx31lite)
 197 ===============================
 198
 199 FIXME
 200
 201
 202 Phytec phyCORE-iMX31 (mx31phy)
 203 ==============================
 204
 205 FIXME
 206
 207
 208                              Consumer Devices
 209                              ================
 210
 211 FIC Neo1973 GTA01 smartphone (fic-gta01)
 212 ========================================
 213
 214 To install Poky on a GTA01 smartphone you will need "dfu-util" tool
 215 which you can build with <command>bitbake dfu-util-native</command>.
 216
 217 Flashing requires these steps:
 218
 219   1. Power down the device.</para>
 220   2. Connect the device to the host machine via USB.
 221   3. Hold AUX key and press Power key. There should be a bootmenu
 222      on screen.
 223   4. Run "dfu-util -l" to check if the phone is visible on the USB bus.
 224      The output should look like this:
 225
 226      dfu-util - (C) 2007 by OpenMoko Inc.
 227      This program is Free Software and has ABSOLUTELY NO WARRANTY
 228
 229      Found Runtime: [0x1457:0x5119] devnum=19, cfg=0, intf=2, alt=0, name="USB Device Firmware Upgrade"
 230
 231   5. Flash the kernel with "dfu-util -a kernel -D uImage-2.6.21.6-moko11-r2-fic-gta01.bin"
 232   6. Flash rootfs with "dfu-util -a rootfs -D <image>", where <image> is the
 233      jffs2 image file to use as the root filesystem
 234      (e.g. ./tmp/deploy/images/poky-image-sato-fic-gta01.jffs2)
 235
 236
 237 HTC Universal (htcuniversal)
 238 ============================
 239
 240 FIXME
 241
 242
 243
 244 Nokia 770/N800/N810 Internet Tablets (nokia770 and nokia800)
 245 ============================================================
 246
 247 Note: Nokia tablet support is highly experimental.
 248
 249 The Nokia internet tablet devices are OMAP based tablet formfactor devices
 250 with large screens (800x480), wifi and touchscreen.
 251
 252 To flash images to these devices you need the "flasher" utility which can be
 253 downloaded from the http://tablets-dev.nokia.com/d3.php?f=flasher-3.0. This
 254 utility needs to be run as root and the usb filesystem needs to be mounted
 255 although most distributions will have done this for you. Once you have this
 256 follow these steps:
 257
 258   1. Power down the device.
 259   2. Connect the device to the host machine via USB
 260      (connecting power to the device doesn't hurt either).
 261   3. Run "flasher -i"
 262   4. Power on the device.
 263   5. The program should give an indication it's found
 264      a tablet device. If not, recheck the cables, make sure you're
 265      root and usbfs/usbdevfs is mounted.
 266   6. Run "flasher -r <image> -k <kernel> -f", where <image> is the
 267      jffs2 image file to use as the root filesystem
 268      (e.g. ./tmp/deploy/images/poky-image-sato-nokia800.jffs2)
 269      and <kernel> is the kernel to use
 270      (e.g. ./tmp/deploy/images/zImage-nokia800.bin).
 271   7. Run "flasher -R" to reboot the device.
 272   8. The device should boot into Poky.
 273
 274 The nokia800 images and kernel will run on both the N800 and N810.
 275
 276
 277 Sharp Zaurus SL-C7x0 series (c7x0)
 278 ==================================
 279
 280 The Sharp Zaurus c7x0 series (SL-C700, SL-C750, SL-C760, SL-C860, SL-7500)
 281 are PXA255 based handheld PDAs with VGA screens. To install Poky images on
 282 these devices follow these steps:
 283
 284   1. Obtain an SD/MMC or CF card with a vfat or ext2 filesystem.
 285   2. Copy a jffs2 image file (e.g. poky-image-sato-c7x0.jffs2) onto the
 286      card as "initrd.bin":
 287
 288      $ cp ./tmp/deploy/images/poky-image-sato-c7x0.jffs2 /path/to/my-cf-card/initrd.bin
 289
 290   3. Copy an Linux kernel file (zImage-c7x0.bin) onto the card as
 291      "zImage.bin":
 292
 293      $ cp ./tmp/deploy/images/zImage-c7x0.bin /path/to/my-cf-card/zImage.bin
 294
 295   4. Copy an updater script (updater.sh.c7x0) onto the card
 296      as "updater.sh":
 297
 298      $ cp ./tmp/deploy/images/updater.sh.c7x0 /path/to/my-cf-card/updater.sh
 299
 300   5. Power down the Zaurus.
 301   6. Hold "OK" key and power on the device. An update menu should appear
 302      (in Japanese).
 303   7. Choose "Update" (item 4).
 304   8. The next screen will ask for the source, choose the appropriate
 305      card (CF or SD).
 306   9. Make sure AC power is connected.
 307   10. The next screen asks for confirmation, choose "Yes" (the left button).
 308   11. The update process will start, flash the files on the card onto
 309       the device and the device will then reboot into Poky.
 310
 311
 312 Sharp Zaurus SL-C1000 (akita)
 313 =============================
 314
 315 The Sharp Zaurus SL-C1000 is a PXA270 based device otherwise similar to the
 316 c7x0. To install Poky images on this device follow the instructions for
 317 the c7x0 but replace "c7x0" with "akita" where appropriate.
 318
 319
 320 Sharp Zaurus SL-C3x00 series (spitz)
 321 ====================================
 322
 323 The Sharp Zaurus SL-C3x00 devices are PXA270 based devices similar
 324 to akita but with an internal microdrive. The installation procedure
 325 assumes a standard microdrive based device where the root (first)
 326 partition has been enlarged to fit the image (at least 100MB,
 327 400MB for the SDK).
 328
 329 The procedure is the same as for the c7x0 and akita models with the
 330 following differences:
 331
 332  1. Instead of a jffs2 image you need to copy a compressed tarball of the
 333     root fileystem (e.g. poky-image-sato-spitz.tar.gz) onto the
 334     card as "hdimage1.tgz":
 335
 336     $ cp ./tmp/deploy/images/poky-image-sato-spitz.tar.gz /path/to/my-cf-card/hdimage1.tgz
 337
 338  2. You additionally need to copy a special tar utility  (gnu-tar) onto
 339     the card as "gnu-tar":
 340
 341     $ cp ./tmp/deploy/images/gnu-tar /path/to/my-cf-card/gnu-tar
 342
 343
 344