README.hardware

                          Poky Hardware README
                          ====================

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.

Support for additional devices is normally added by creating BSP layers - for
more information please see the Yocto Board Support Package (BSP) Developer's
Guide - documentation source is in documentation/bspguide or download the PDF
from:

   http://yoctoproject.org/community/documentation

Support for machines other than QEMU may be moved out to separate BSP layers in
future versions.


QEMU Emulation Targets
======================

To simplify development Poky supports building images to work with the QEMU
emulator in system emulation mode. Several architectures are currently
supported:

  * ARM (qemuarm)
  * x86 (qemux86)
  * x86-64 (qemux86-64)
  * PowerPC (qemuppc)
  * MIPS (qemumips)

Use of the QEMU images is covered in the Poky Reference Manual. The Poky
MACHINE setting corresponding to the target is given in brackets.


Hardware Reference Boards
=========================

The following boards are supported by Poky's core layer:

  * Texas Instruments Beagleboard (beagleboard)
  * Freescale MPC8315E-RDB (mpc8315e-rdb)
  * Ubiquiti Networks RouterStation Pro (routerstationpro)

For more information see the 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's core layer:

  * Intel Atom based PCs and devices (atom-pc)

For more information see the device's section below. The Poky MACHINE setting
corresponding to the device is given in brackets.



                      Specific Hardware Documentation
                      ===============================


Intel Atom based PCs and devices (atom-pc)
==========================================

The atom-pc MACHINE is tested on the following platforms:

  o Asus EeePC 901
  o Acer Aspire One
  o Toshiba NB305
  o Intel Embedded Development Board 1-N450 (Black Sand)

and is likely to work on many unlisted Atom based devices. The MACHINE type
supports ethernet, wifi, sound, and i915 graphics by default in addition to
common PC input devices, busses, and so on.

Depending on the device, it can boot from a traditional hard-disk, a USB device,
or over the network. Writing poky generated images to physical media is
straightforward with a caveat for USB devices. The following examples assume the
target boot device is /dev/sdb, be sure to verify this and use the correct
device as the following commands are run as root and are not reversable.

USB Device:
  1. Build a live image. This image type consists of a simple filesystem
     without a partition table, which is suitable for USB keys, and with the
     default setup for the atom-pc machine, this image type is built
     automatically for any image you build. For example:

     $ bitbake core-image-minimal

  2. Use the "dd" utility to write the image to the raw block device. For
     example:

     # dd if=core-image-minimal-atom-pc.hddimg of=/dev/sdb

  If the device fails to boot with "Boot error" displayed, or apparently
  stops just after the SYSLINUX version banner, it is likely the BIOS cannot
  understand the physical layout of the disk (or rather it expects a
  particular layout and cannot handle anything else). There are two possible
  solutions to this problem:

  1. Change the BIOS USB Device setting to HDD mode. The label will vary by
     device, but the idea is to force BIOS to read the Cylinder/Head/Sector
     geometry from the device.

  2. Without such an option, the BIOS generally boots the device in USB-ZIP
     mode. To write an image to a USB device that will be bootable in
     USB-ZIP mode, carry out the following actions:

     a. Determine the geometry of your USB device using fdisk:

     # fdisk /dev/sdb
     Command (m for help): p

     Disk /dev/sdb: 4011 MB, 4011491328 bytes
     124 heads, 62 sectors/track, 1019 cylinders, total 7834944 sectors
     ...

     Command (m for help): q

     b. Configure the USB device for USB-ZIP mode:
     
     # mkdiskimage -4 /dev/sdb 1019 124 62

     Where 1019, 124 and 62 are the cylinder, head and sectors/track counts
     as reported by fdisk (substitute the values reported for your device).
     When the operation has finished and the access LED (if any) on the
     device stops flashing, remove and reinsert the device to allow the
     kernel to detect the new partition layout.

     c. Copy the contents of the poky image to the USB-ZIP mode device:

     # mkdir /tmp/image
     # mkdir /tmp/usbkey
     # mount -o loop core-image-minimal-atom-pc.hddimg  /tmp/image
     # mount /dev/sdb4 /tmp/usbkey
     # cp -rf /tmp/image/* /tmp/usbkey

     d. Install the syslinux boot loader:

     # syslinux /dev/sdb4

     e. Unmount everything:

     # umount /tmp/image
     # umount /tmp/usbkey

  Install the boot device in the target board and configure the BIOS to boot
  from it.

  For more details on the USB-ZIP scenario, see the syslinux documentation:
  http://git.kernel.org/?p=boot/syslinux/syslinux.git;a=blob_plain;f=doc/usbkey.txt;hb=HEAD


Texas Instruments Beagleboard (beagleboard)
===========================================

The Beagleboard is an ARM Cortex-A8 development board with USB, DVI-D, S-Video,
2D/3D accelerated graphics, audio, serial, JTAG, and SD/MMC. The xM adds a
faster CPU, more RAM, an ethernet port, more USB ports, microSD, and removes
the NAND flash. The beagleboard MACHINE is tested on the following platforms:

  o Beagleboard C4
  o Beagleboard xM rev A & B

The Beagleboard C4 has NAND, while the xM does not. For the sake of simplicity,
these instructions assume you have erased the NAND on the C4 so its boot
behavior matches that of the xM. To do this, issue the following commands from
the u-boot prompt (note that the unlock may be unecessary depending on the
version of u-boot installed on your board and only one of the erase commands
will succeed):

    # nand unlock
    # nand erase
    # nand erase.chip

To further tailor these instructions for your board, please refer to the
documentation at http://www.beagleboard.org.

From a Linux system with access to the image files perform the following steps
as root, replacing mmcblk0* with the SD card device on your machine (such as sdc
if used via a usb card reader):

  1. Partition and format an SD card:
     # fdisk -lu /dev/mmcblk0
     
     Disk /dev/mmcblk0: 3951 MB, 3951034368 bytes
     255 heads, 63 sectors/track, 480 cylinders, total 7716864 sectors
     Units = sectors of 1 * 512 = 512 bytes
     
             Device Boot      Start         End      Blocks  Id System
     /dev/mmcblk0p1   *          63      144584       72261   c Win95 FAT32 (LBA)
     /dev/mmcblk0p2          144585      465884      160650  83 Linux

     # mkfs.vfat -F 16 -n "boot" /dev/mmcblk0p1
     # mke2fs -j -L "root" /dev/mmcblk0p2

  The following assumes the SD card partition 1 and 2 are mounted at
  /media/boot and /media/root respectively. Removing the card and reinserting
  it will do just that on most modern Linux desktop environments.
  
  The files referenced below are made available after the build in
  build/tmp/deploy/images.

  2. Install the boot loaders
     # cp MLO-beagleboard /media/boot/MLO
     # cp u-boot-beagleboard.bin /media/boot/u-boot.bin

  3. Install the root filesystem
     # tar x -C /media/root -f core-image-$IMAGE_TYPE-beagleboard.tar.bz2
     # tar x -C /media/root -f modules-$KERNEL_VERSION-beagleboard.tgz

  4. Install the kernel uImage
     # cp uImage-beagleboard.bin /media/boot/uImage

  5. Prepare a u-boot script to simplify the boot process
     The Beagleboard can be made to boot at this point from the u-boot command
     shell. To automate this process, generate a user.scr script as follows.

     Install uboot-mkimage (from uboot-mkimage on Ubuntu or uboot-tools on Fedora).

     Prepare a script config:

     # (cat << EOF
     setenv bootcmd 'mmc init; fatload mmc 0:1 0x80300000 uImage; bootm 0x80300000'
     setenv bootargs 'console=tty0 console=ttyO2,115200n8 root=/dev/mmcblk0p2 rootwait rootfstype=ext3 ro'
     boot
     EOF
     ) > serial-boot.cmd
     # mkimage -A arm -O linux -T script -C none -a 0 -e 0 -n "Core Minimal" -d ./serial-boot.cmd ./boot.scr
     # cp boot.scr /media/boot

   6. Unmount the SD partitions, insert the SD card into the Beagleboard, and
      boot the Beagleboard

Note: As of the 2.6.37 linux-yocto kernel recipe, the Beagleboard uses the
      OMAP_SERIAL device (ttyO2). If you are using an older kernel, such as the
      2.6.34 linux-yocto-stable, be sure to replace ttyO2 with ttyS2 above. You
      should also override the machine SERIAL_CONSOLE in your local.conf in
      order to setup the getty on the serial line:

      SERIAL_CONSOLE_beagleboard = "115200 ttyS2"


Freescale MPC8315E-RDB (mpc8315e-rdb)
=====================================

The MPC8315 PowerPC reference platform (MPC8315E-RDB) is aimed at hardware and
software development of network attached storage (NAS) and digital media server
applications. The MPC8315E-RDB features the PowerQUICC II Pro processor, which
includes a built-in security accelerator.

(Note: you may find it easier to order MPC8315E-RDBA; this appears to be the
same board in an enclosure with accessories. In any case it is fully
compatible with the instructions given here.)

Setup instructions
------------------

You will need the following:
* NFS root setup on your workstation
* TFTP server installed on your workstation
* Straight-thru 9-conductor serial cable (DB9, M/F) connected from your 
  PC to UART1
* Ethernet connected to the first ethernet port on the board

--- Preparation ---

Note: if you have altered your board's ethernet MAC address(es) from the
defaults, or you need to do so because you want multiple boards on the same
network, then you will need to change the values in the dts file (patch
linux/arch/powerpc/boot/dts/mpc8315erdb.dts within the kernel source). If
you have left them at the factory default then you shouldn't need to do
anything here.

--- Booting from NFS root ---

Load the kernel and dtb (device tree blob), and boot the system as follows:

 1. Get the kernel (uImage-mpc8315e-rdb.bin) and dtb (uImage-mpc8315e-rdb.dtb)
    files from the Poky build tmp/deploy directory, and make them available on
    your TFTP server.

 2. Connect the board's first serial port to your workstation and then start up
    your favourite serial terminal so that you will be able to interact with
    the serial console. If you don't have a favourite, picocom is suggested:

  $ picocom /dev/ttyUSB0 -b 115200

 3. Power up or reset the board and press a key on the terminal when prompted
    to get to the U-Boot command line

 4. Set up the environment in U-Boot:

 => setenv ipaddr <board ip>
 => setenv serverip <tftp server ip>
 => setenv bootargs root=/dev/nfs rw nfsroot=<nfsroot ip>:<rootfs path> ip=<board ip>:<server ip>:<gateway ip>:255.255.255.0:mpc8315e:eth0:off console=ttyS0,115200

 5. Download the kernel and dtb, and boot:

 => tftp 800000 uImage-mpc8315e-rdb.bin
 => tftp 780000 uImage-mpc8315e-rdb.dtb
 => bootm 800000 - 780000


Ubiquiti Networks RouterStation Pro (routerstationpro)
======================================================

The RouterStation Pro is an Atheros AR7161 MIPS-based board. Geared towards
networking applications, it has all of the usual features as well as three
type IIIA mini-PCI slots and an on-board 3-port 10/100/1000 Ethernet switch,
in addition to the 10/100/1000 Ethernet WAN port which supports
Power-over-Ethernet.

Setup instructions
------------------

You will need the following:
* A serial cable - female to female (or female to male + gender changer)
  NOTE: cable must be straight through, *not* a null modem cable.
* USB flash drive or hard disk that is able to be powered from the
  board's USB port.
* tftp server installed on your workstation

NOTE: in the following instructions it is assumed that /dev/sdb corresponds
to the USB disk when it is plugged into your workstation. If this is not the
case in your setup then please be careful to substitute the correct device
name in all commands where appropriate.

--- Preparation ---

1) Build an image (e.g. core-image-minimal) using "routerstationpro" as the
MACHINE

2) Partition the USB drive so that primary partition 1 is type Linux (83).
Minimum size depends on your root image size - core-image-minimal probably
only needs 8-16MB, other images will need more.

  # fdisk /dev/sdb
  Command (m for help): p

  Disk /dev/sdb: 4011 MB, 4011491328 bytes
  124 heads, 62 sectors/track, 1019 cylinders, total 7834944 sectors
  Units = sectors of 1 * 512 = 512 bytes
  Sector size (logical/physical): 512 bytes / 512 bytes
  I/O size (minimum/optimal): 512 bytes / 512 bytes
  Disk identifier: 0x0009e87d

     Device Boot      Start         End      Blocks   Id  System
  /dev/sdb1              62     1952751      976345   83  Linux

3) Format partition 1 on the USB as ext3

  # mke2fs -j /dev/sdb1

4) Mount partition 1 and then extract the contents of
tmp/deploy/images/core-image-XXXX.tar.bz2 into it (preserving permissions).

  # mount /dev/sdb1 /media/sdb1
  # cd /media/sdb1
  # tar -xvjpf tmp/deploy/images/core-image-XXXX.tar.bz2

5) Unmount the USB drive and then plug it into the board's USB port

6) Connect the board's serial port to your workstation and then start up
your favourite serial terminal so that you will be able to interact with
the serial console. If you don't have a favourite, picocom is suggested:

  $ picocom /dev/ttyUSB0 -b 115200

7) Connect the network into eth0 (the one that is NOT the 3 port switch). If
you are using power-over-ethernet then the board will power up at this point.

8) Start up the board, watch the serial console. Hit Ctrl+C to abort the
autostart if the board is configured that way (it is by default). The
bootloader's fconfig command can be used to disable autostart and configure
the IP settings if you need to change them (default IP is 192.168.1.20).

9) Make the kernel (tmp/deploy/images/vmlinux-routerstationpro.bin) available
on the tftp server.

10) If you are going to write the kernel to flash (optional - see "Booting a
kernel directly" below for the alternative), remove the current kernel and
rootfs flash partitions. You can list the partitions using the following
bootloader command:

  RedBoot> fis list

You can delete the existing kernel and rootfs with these commands:

  RedBoot> fis delete kernel
  RedBoot> fis delete rootfs

--- Booting a kernel directly ---

1) Load the kernel using the following bootloader command:

  RedBoot> load -m tftp -h <ip of tftp server> vmlinux-routerstationpro.bin

You should see a message on it being successfully loaded.

2) Execute the kernel:

  RedBoot> exec -c "console=ttyS0,115200 root=/dev/sda1 rw rootdelay=2 board=UBNT-RSPRO"

Note that specifying the command line with -c is important as linux-yocto does
not provide a default command line.

--- Writing a kernel to flash ---

1) Go to your tftp server and gzip the kernel you want in flash. It should
halve the size.

2) Load the kernel using the following bootloader command:

  RedBoot> load -r -b 0x80600000 -m tftp -h <ip of tftp server> vmlinux-routerstationpro.bin.gz

This should output something similar to the following:

  Raw file loaded 0x80600000-0x8087c537, assumed entry at 0x80600000

Calculate the length by subtracting the first number from the second number
and then rounding the result up to the nearest 0x1000.

3) Using the length calculated above, create a flash partition for the kernel:

  RedBoot> fis create -b 0x80600000 -l 0x240000 kernel

(change 0x240000 to your rounded length -- change "kernel" to whatever
you want to name your kernel)

--- Booting a kernel from flash ---

To boot the flashed kernel perform the following steps.

1) At the bootloader prompt, load the kernel:

  RedBoot> fis load -d -e kernel

(Change the name "kernel" above if you chose something different earlier)

(-e means 'elf', -d 'decompress')

2) Execute the kernel using the exec command as above.

--- Automating the boot process ---

After writing the kernel to flash and testing the load and exec commands
manually, you can automate the boot process with a boot script.

1) RedBoot> fconfig
   (Answer the questions not specified here as they pertain to your environment)
2) Run script at boot: true
  Boot script: 
  .. fis load -d -e kernel
  .. exec
  Enter script, terminate with empty line
  >> fis load -d -e kernel
  >> exec -c "console=ttyS0,115200 root=/dev/sda1 rw rootdelay=2 board=UBNT-RSPRO"
  >> 
3) Answer the remaining questions and write the changes to flash:
  Update RedBoot non-volatile configuration - continue (y/n)? y
  ... Erase from 0xbfff0000-0xc0000000: .
  ... Program from 0x87ff0000-0x88000000 at 0xbfff0000: .
4) Power cycle the board.