1 Poky Hardware Reference Guide
2 =============================
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.
10 QEMU Emulation Images (qemuarm and qemux86)
11 ===========================================
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
18 Hardware Reference Boards
19 =========================
21 The following boards are supported by Poky:
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 (mx31litekit)
28 * Phytec phyCORE-iMX31 (mx31phy)
29 * Texas Instruments Beagleboard (beagleboard)
31 For more information see board's section below. The Poky MACHINE setting
32 corresponding to the board is given in brackets.
37 The following consumer devices are supported by Poky:
39 * FIC Neo1973 GTA01 smartphone (fic-gta01)
40 * HTC Universal (htcuniversal)
41 * Nokia 770/N800/N810 Internet Tablets (nokia770 and nokia800)
42 * Sharp Zaurus SL-C7x0 series (c7x0)
43 * Sharp Zaurus SL-C1000 (akita)
44 * Sharp Zaurus SL-C3x00 series (spitz)
46 For more information see board's section below. The Poky MACHINE setting
47 corresponding to the board is given in brackets.
50 Hardware Reference Boards
51 =========================
53 Compulab CM-X270 (cm-x270)
54 ==========================
56 The bootloader on this board doesn't support writing jffs2 images directly to
57 NAND and normally uses a proprietary kernel flash driver. To allow the use of
58 jffs2 images, a two stage updating procedure is needed. Firstly, an initramfs
59 is booted which contains mtd utilities and this is then used to write the main
62 It is assumed the board is connected to a network where a TFTP server is
63 available and that a serial terminal is available to communicate with the
64 bootloader (38400, 8N1). If a DHCP server is available the device will use it
65 to obtain an IP address. If not, run:
67 ARMmon > setip dhcp off
68 ARMmon > setip ip 192.168.1.203
69 ARMmon > setip mask 255.255.255.0
71 To reflash the kernel:
73 ARMmon > download kernel tftp zimage 192.168.1.202
76 where zimage is the name of the kernel on the TFTP server and its IP address is
77 192.168.1.202. The names of the files must be all lowercase.
79 To reflash the initrd/initramfs:
81 ARMmon > download ramdisk tftp diskimage 192.168.1.202
82 ARMmon > flash ramdisk
84 where diskimage is the name of the initramfs image (a cpio.gz file).
86 To boot the initramfs:
89 ARMmon > bootos "console=ttyS0,38400 rdinit=/sbin/init"
91 To reflash the main image login to the system as user "root", then run:
93 # ifconfig eth0 192.168.1.203
94 # tftp -g -r mainimage 192.168.1.202
95 # flash_eraseall /dev/mtd1
96 # nandwrite /dev/mtd1 mainimage
98 which configures the network interface with the IP address 192.168.1.203,
99 downloads the "mainimage" file from the TFTP server at 192.168.1.202, erases
100 the flash and then writes the new image to the flash.
102 The main image can then be booted with:
104 ARMmon > bootos "console=ttyS0,38400 root=/dev/mtdblock1 rootfstype=jffs2"
106 Note that the initramfs image is built by poky in a slightly different mode to
107 normal since it uses uclibc. To generate this use a command like:
109 IMAGE_FSTYPES=cpio.gz MACHINE=cm-x270 POKYLIBC=uclibc bitbake poky-image-minimal-mtdutils
112 Compulab EM-X270 (em-x270)
113 ==========================
115 Fetch the "Linux - kernel and run-time image (Angstrom)" ZIP file from the
116 Compulab website. Inside the images directory of this ZIP file is another ZIP
117 file called 'LiveDisk.zip'. Extract this over a cleanly formatted vfat USB flash
118 drive. Replace the 'em_x270.img' file with the 'updater-em-x270.ext2' file.
120 Insert this USB disk into the supplied adapter and connect this to the
121 board. Whilst holding down the the suspend button press the reset button. The
122 board will now boot off the USB key and into a version of Angstrom. On the
123 desktop is an icon labelled "Updater". Run this program to launch the updater
124 that will flash the Poky kernel and rootfs to the board.
127 FreeScale iMX31ADS (mx31ads)
128 ===========================
130 The correct serial port is the top-most female connector to the right of the
133 For uploading data to RedBoot we are going to use tftp. In this example we
134 assume that the tftpserver is on 192.168.9.1 and the board is on192.168.9.2.
136 To set the IP address, run:
138 ip_address -l 192.168.9.2/24 -h 192.168.9.1
140 To download a kernel called "zimage" from the TFTP server, run:
142 load -r -b 0x100000 zimage
144 To write the kernel to flash run:
148 To download a rootfs jffs2 image "rootfs" from the TFTP server, run:
150 load -r -b 0x100000 rootfs
152 To write the root filesystem to flash run:
156 To load and boot a kernel and rootfs from flash:
159 exec -b 0x100000 -l 0x200000 -c "noinitrd console=ttymxc0,115200 root=/dev/mtdblock2 rootfstype=jffs2 init=linuxrc ip=none"
161 To load and boot a kernel from a TFTP server with the rootfs over NFS:
163 load -r -b 0x100000 zimage
164 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"
166 The instructions above are for using the (default) NOR flash on the board,
167 there is also 128M of NAND flash. It is possible to install Poky to the NAND
168 flash which gives more space for the rootfs and instructions for using this are
169 given below. To switch to the NAND flash:
173 This will then restart RedBoot using the NAND rather than the NOR. If you
174 have not used the NAND before then it is unlikely that there will be a
175 partition table yet. You can get the list of partitions with 'fis list'.
177 If this shows no partitions then you can create them with:
181 The output of 'fis list' should now show:
183 Name FLASH addr Mem addr Length Entry point
184 RedBoot 0xE0000000 0xE0000000 0x00040000 0x00000000
185 FIS directory 0xE7FF4000 0xE7FF4000 0x00003000 0x00000000
186 RedBoot config 0xE7FF7000 0xE7FF7000 0x00001000 0x00000000
188 Partitions for the kernel and rootfs need to be created:
190 fis create -l 0x1A0000 -e 0x00100000 kernel
191 fis create -l 0x5000000 -e 0x00100000 root
193 You may now use the instructions above for flashing. However it is important
194 to note that the erase block size for the NAND is different to the NOR so the
195 JFFS erase size will need to be changed to 0x4000. Stardard images are built
196 for NOR and you will need to build custom images for NAND.
198 You will also need to update the kernel command line to use the correct root
199 filesystem. This should be '/dev/mtdblock7' if you adhere to the partitioning
200 scheme shown above. If this fails then you can doublecheck against the output
201 from the kernel when it evaluates the available mtd partitions.
204 Marvell PXA3xx Zylonite (zylonite)
205 ==================================
207 These instructions assume the Zylonite is connected to a machine running a TFTP
208 server at address 192.168.123.5 and that a serial link (38400 8N1) is available
209 to access the blob bootloader. The kernel is on the TFTP server as
210 "zylonite-kernel" and the root filesystem jffs2 file is "zylonite-rootfs" and
211 the images are to be saved in NAND flash.
213 The following commands setup blob:
215 blob> setip client 192.168.123.4
216 blob> setip server 192.168.123.5
220 blob> tftp zylonite-kernel
221 blob> nandwrite -j 0x80800000 0x60000 0x200000
225 blob> tftp zylonite-rootfs
226 blob> nanderase -j 0x260000 0x5000000
227 blob> nandwrite -j 0x80800000 0x260000 <length>
229 (where <length> is the rootfs size which will be printed by the tftp step)
237 Logic iMX31 Lite Kit (mx31litekit)
238 ===============================
240 The easiest method to boot this board is to take an MMC/SD card and format
241 the first partition as ext2, then extract the poky image onto this as root.
242 Assuming the board is network connected, a TFTP server is available at
243 192.168.1.33 and a serial terminal is available (115200 8N1), the following
244 commands will boot a kernel called "mx31kern" from the TFTP server:
246 losh> ifconfig sm0 192.168.1.203 255.255.255.0 192.168.1.33
247 losh> load raw 0x80100000 0x200000 /tftp/192.168.1.33:mx31kern
248 losh> exec 0x80100000 -
251 Phytec phyCORE-iMX31 (mx31phy)
252 ==============================
254 Support for this board is currently being developed. Experimental jffs2
255 images and a suitable kernel are available and are known to work with the
262 FIC Neo1973 GTA01 smartphone (fic-gta01)
263 ========================================
265 To install Poky on a GTA01 smartphone you will need "dfu-util" tool
266 which you can build with "bitbake dfu-util-native" command.
268 Flashing requires these steps:
270 1. Power down the device.
271 2. Connect the device to the host machine via USB.
272 3. Hold AUX key and press Power key. There should be a bootmenu
274 4. Run "dfu-util -l" to check if the phone is visible on the USB bus.
275 The output should look like this:
277 dfu-util - (C) 2007 by OpenMoko Inc.
278 This program is Free Software and has ABSOLUTELY NO WARRANTY
280 Found Runtime: [0x1457:0x5119] devnum=19, cfg=0, intf=2, alt=0, name="USB Device Firmware Upgrade"
282 5. Flash the kernel with "dfu-util -a kernel -D uImage-2.6.21.6-moko11-r2-fic-gta01.bin"
283 6. Flash rootfs with "dfu-util -a rootfs -D <image>", where <image> is the
284 jffs2 image file to use as the root filesystem
285 (e.g. ./tmp/deploy/images/poky-image-sato-fic-gta01.jffs2)
288 HTC Universal (htcuniversal)
289 ============================
291 Note: HTC Universal support is highly experimental.
293 On the HTC Universal, entirely replacing the Windows installation is not
294 supported, instead Poky is booted from an MMC/SD card from Windows. Once Poky
295 has booted, Windows is no longer in memory or active but when power is removed,
296 the user will be returned to windows and will need to return to Linux from
299 Once an MMC/SD card is available it is suggested its split into two partitions,
300 one for a program called HaRET which lets you boot Linux from within Windows
301 and the second for the rootfs. The HaRET partition should be the first partition
302 on the card and be vfat formatted. It doesn't need to be large, just enough for
303 HaRET and a kernel (say 5MB max). The rootfs should be ext2 and is usually the
304 second partition. The first partition should be vfat so Windows recognises it
305 as if it doesn't, it has been known to reformat cards.
307 On the first partition you need three files:
309 * a HaRET binary (version 0.5.1 works well and a working version
310 should be part of the last Poky release)
311 * a kernel renamed to "zImage"
312 * a default.txt which contains:
316 set cmdline "root=/dev/mmcblk0p2 rw console=ttyS0,115200n8 console=tty0 rootdelay=5 fbcon=rotate:1"
319 On the second parition the root file system is extracted as root. A different
320 partition layout or other kernel options can be changed in the default.txt file.
322 When inserted into the device, Windows should see the card and let you browse
323 its contents using File Explorer. Running the HaRET binary will present a dialog
324 box (maybe after messages warning about running unsigned binaries) where you
325 select OK and you should then see Poky boot. Kernel messages can be seen by
326 adding psplash=false to the kernel commandline.
329 Nokia 770/N800/N810 Internet Tablets (nokia770 and nokia800)
330 ============================================================
332 Note: Nokia tablet support is highly experimental.
334 The Nokia internet tablet devices are OMAP based tablet formfactor devices
335 with large screens (800x480), wifi and touchscreen.
337 To flash images to these devices you need the "flasher" utility which can be
338 downloaded from the http://tablets-dev.nokia.com/d3.php?f=flasher-3.0. This
339 utility needs to be run as root and the usb filesystem needs to be mounted
340 although most distributions will have done this for you. Once you have this
343 1. Power down the device.
344 2. Connect the device to the host machine via USB
345 (connecting power to the device doesn't hurt either).
347 4. Power on the device.
348 5. The program should give an indication it's found
349 a tablet device. If not, recheck the cables, make sure you're
350 root and usbfs/usbdevfs is mounted.
351 6. Run "flasher -r <image> -k <kernel> -f", where <image> is the
352 jffs2 image file to use as the root filesystem
353 (e.g. ./tmp/deploy/images/poky-image-sato-nokia800.jffs2)
354 and <kernel> is the kernel to use
355 (e.g. ./tmp/deploy/images/zImage-nokia800.bin).
356 7. Run "flasher -R" to reboot the device.
357 8. The device should boot into Poky.
359 The nokia800 images and kernel will run on both the N800 and N810.
362 Sharp Zaurus SL-C7x0 series (c7x0)
363 ==================================
365 The Sharp Zaurus c7x0 series (SL-C700, SL-C750, SL-C760, SL-C860, SL-7500)
366 are PXA25x based handheld PDAs with VGA screens. To install Poky images on
367 these devices follow these steps:
369 1. Obtain an SD/MMC or CF card with a vfat or ext2 filesystem.
370 2. Copy a jffs2 image file (e.g. poky-image-sato-c7x0.jffs2) onto the
371 card as "initrd.bin":
373 $ cp ./tmp/deploy/images/poky-image-sato-c7x0.jffs2 /path/to/my-cf-card/initrd.bin
375 3. Copy an Linux kernel file (zImage-c7x0.bin) onto the card as
378 $ cp ./tmp/deploy/images/zImage-c7x0.bin /path/to/my-cf-card/zImage.bin
380 4. Copy an updater script (updater.sh.c7x0) onto the card
383 $ cp ./tmp/deploy/images/updater.sh.c7x0 /path/to/my-cf-card/updater.sh
385 5. Power down the Zaurus.
386 6. Hold "OK" key and power on the device. An update menu should appear
388 7. Choose "Update" (item 4).
389 8. The next screen will ask for the source, choose the appropriate
391 9. Make sure AC power is connected.
392 10. The next screen asks for confirmation, choose "Yes" (the left button).
393 11. The update process will start, flash the files on the card onto
394 the device and the device will then reboot into Poky.
397 Sharp Zaurus SL-C1000 (akita)
398 =============================
400 The Sharp Zaurus SL-C1000 is a PXA270 based device otherwise similar to the
401 c7x0. To install Poky images on this device follow the instructions for
402 the c7x0 but replace "c7x0" with "akita" where appropriate.
405 Sharp Zaurus SL-C3x00 series (spitz)
406 ====================================
408 The Sharp Zaurus SL-C3x00 devices are PXA270 based devices similar
409 to akita but with an internal microdrive. The installation procedure
410 assumes a standard microdrive based device where the root (first)
411 partition has been enlarged to fit the image (at least 100MB,
414 The procedure is the same as for the c7x0 and akita models with the
415 following differences:
417 1. Instead of a jffs2 image you need to copy a compressed tarball of the
418 root fileystem (e.g. poky-image-sato-spitz.tar.gz) onto the
419 card as "hdimage1.tgz":
421 $ cp ./tmp/deploy/images/poky-image-sato-spitz.tar.gz /path/to/my-cf-card/hdimage1.tgz
423 2. You additionally need to copy a special tar utility (gnu-tar) onto
424 the card as "gnu-tar":
426 $ cp ./tmp/deploy/images/gnu-tar /path/to/my-cf-card/gnu-tar
429 Intel Atom based PCs and devices (atom-pc)
430 ==========================================
432 The atom-pc MACHINE is tested on the following platforms:
437 o Intel Embedded Development Board 1-N450 (Black Sand)
439 and is likely to work on many unlisted atom based devices. The MACHINE type
440 supports ethernet, wifi, sound, and i915 graphics by default in addition to
441 common PC input devices, busses, and so on.
443 Depending on the device, it can boot from a traditional hard-disk, a USB device,
444 or over the network. Writing poky generated images to physical media is
445 straightforward with a caveat for USB devices. The following examples assume the
446 target boot device is /dev/sdb, be sure to verify this and use the correct
447 device as the following commands are run as root and are not reversable.
450 1. Build a directdisk image format. This will generate proper partition tables
451 that will in turn be written to the physical media. For example:
453 $ bitbake poky-image-minimal-directdisk
455 2. Use the "dd" utility to write the image to the raw block device. For example:
457 # dd if=poky-image-minimal-directdisk-atom-pc.hdddirect of=/dev/sdb
460 1. Build an hddimg image format. This is a simple filesystem without partition
461 tables and is suitable for USB keys. For example:
463 $ bitbake poky-image-minimal-live
465 2. Use the "dd" utility to write the image to the raw block device. For
468 # dd if=poky-image-minimal-live-atom-pc.hddimg of=/dev/sdb
470 If the device fails to boot with "Boot error" displayed, it is likely the BIOS
471 cannot understand the physical layout of the disk (or rather it expects a
472 particular layout and cannot handle anything else). There are two possible
473 solutions to this problem:
475 1. Change the BIOS USB Device setting to HDD mode. The label will vary by
476 device, but the idea is to force BIOS to read the Cylinder/Head/Sector
477 geometry from the device.
479 2. Without such an option, the BIOS generally boots the device in USB-ZIP
482 a. Configure the USB device for USB-ZIP mode:
484 # mkdiskimage -4 /dev/sdb 0 63 62
486 Where 63 and 62 are the head and sector count as reported by fdisk.
487 Remove and reinsert the device to allow the kernel to detect the new
490 b. Copy the contents of the poky image to the USB-ZIP mode device:
492 # mount -o loop poky-image-minimal-live-atom-pc.hddimg /tmp/image
493 # mount /dev/sdb4 /tmp/usbkey
494 # cp -rf /tmp/image/* /tmp/usbkey
496 c. Install the syslinux boot loader:
500 Install the boot device in the target board and configure the BIOS to boot
503 For more details on the USB-ZIP scenario, see the syslinux documentation:
504 http://git.kernel.org/?p=boot/syslinux/syslinux.git;a=blob_plain;f=doc/usbkey.txt;hb=HEAD
507 Texas Instruments Beagleboard (beagleboard)
508 ===========================================
510 The Beagleboard is an ARM Cortex-A8 development board with USB, DVI-D, S-Video,
511 2D/3D accelerated graphics, audio, serial, JTAG, and SD/MMC. The xM adds a
512 faster CPU, more RAM, an ethernet port, more USB ports, microSD, and removes
513 the NAND flash. The beagleboard MACHINE is tested on the following platforms:
517 TODO: need someone with a Beagleboard C4 to verify these instructions.
519 Due to the lack of NAND on the xM, the install and boot process varies a bit
520 between boards. The C4 can run the x-loader and u-boot binaries from NAND or
521 the SD, while the xM can only run them from the SD. The following instructions
522 apply to both the C4 and the xM, but te C4 can skip step 2 (as noted below),
523 and may require modification of the NAND environment.
525 1. Partition and format an SD card:
526 # fdisk -lu /dev/mmcblk0
528 Disk /dev/mmcblk0: 3951 MB, 3951034368 bytes
529 255 heads, 63 sectors/track, 480 cylinders, total 7716864 sectors
530 Units = sectors of 1 * 512 = 512 bytes
532 Device Boot Start End Blocks Id System
533 /dev/mmcblk0p1 * 63 144584 72261 c Win95 FAT32 (LBA)
534 /dev/mmcblk0p2 144585 465884 160650 83 Linux
536 # mkfs.vfat -F 16 -n "boot" /dev/mmcblk0p1
537 # mke2fs -j -L "root" /dev/mmcblk0p2
539 The following assumes the SD card partition 1 and 2 are mounted at
540 /media/boot and /media/root respectively. The files referenced here
541 are made available after the build in build/tmp/deploy/images.
543 2. Install the boot loaders
544 This step can be omitted for the C4 as it can have the x-loader and
545 u-boot installed in NAND.
547 # cp MLO-beagleboard /media/boot/MLO
548 # cp u-boot-beagleboard.bin /media/boot/u-boot.bin
550 3. Install the root filesystem
551 # tar x -C /media/root -f poky-image-$IMAGE_TYPE-beagleboard.tar.bz2
552 # tar x -C /media/root -f modules-$KERNEL_VERSION-beagleboard.tgz
554 4. Install the kernel uImage
555 # cp uImage-beagleboard.bin /media/boot/uImage
557 5. Prepare a u-boot script to simplify the boot process
558 The Beagleboard can be made to boot at this point from the u-boot command
559 shell. To automate this process, generate a user.scr script as follows.
561 Install uboot-mkimage (from uboot-mkimage on Ubuntu or uboot-tools on Fedora).
563 Prepare a script config:
566 setenv bootcmd 'mmc init; fatload mmc 0:1 0x80300000 uImage; bootm 0x80300000'
567 setenv bootargs 'console=tty0 console=ttyS2,115200n8 root=/dev/mmcblk0p2 rootwait rootfstype=ext3 ro'
571 # mkimage -A arm -O linux -T script -C none -a 0 -e 0 -n "Poky Minimal" -d ./serial-boot.cmd ./user.scr
572 # cp user.scr /media/boot
574 6. Unmount the SD partitions and boot the Beagleboard