1 files changed, 494 insertions, 0 deletions

diff --git a/README.hardware b/README.hardware
new file mode 100644
index 0000000000..607062b59a
--- /dev/null
+++ b/README.hardware
@@ -0,0 +1,494 @@
+                          Poky Hardware README
+                          ====================
+
+This file gives details about using Poky with the reference machines
+supported out of the box. A full list of supported reference target machines
+can be found by looking in the following directories:
+
+   meta/conf/machine/
+   meta-yocto-bsp/conf/machine/
+
+If you are in doubt about using Poky/OpenEmbedded 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/documentation
+
+Support for physical reference hardware has now been split out into a
+meta-yocto-bsp layer which can be removed separately from other layers if not
+needed.
+
+
+QEMU Emulation Targets
+======================
+
+To simplify development, the build system 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 Yocto Project Reference Manual.
+The appropriate MACHINE variable value corresponding to the target is given
+in brackets.
+
+
+Hardware Reference Boards
+=========================
+
+The following boards are supported by the meta-yocto-bsp 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 appropriate MACHINE
+variable value corresponding to the board is given in brackets.
+
+
+Consumer Devices
+================
+
+The following consumer devices are supported by the meta-yocto-bsp layer:
+
+  * Intel x86 based PCs and devices (genericx86)
+
+For more information see the device's section below. The appropriate MACHINE
+variable value corresponding to the device is given in brackets.
+
+
+
+                      Specific Hardware Documentation
+                      ===============================
+
+
+Intel x86 based PCs and devices (genericx86)
+==========================================
+
+The genericx86 MACHINE is tested on the following platforms:
+
+Intel Xeon/Core i-Series:
+  + Intel Romley Server: Sandy Bridge Xeon processor, C600 PCH (Patsburg), (Canoe Pass CRB)
+  + Intel Romley Server: Ivy Bridge Xeon processor, C600 PCH (Patsburg), (Intel SDP S2R3)
+  + Intel Crystal Forest Server: Sandy Bridge Xeon processor, DH89xx PCH (Cave Creek), (Stargo CRB)
+  + Intel Chief River Mobile: Ivy Bridge Mobile processor, QM77 PCH (Panther Point-M), (Emerald Lake II CRB, Sabino Canyon CRB)
+  + Intel Huron River Mobile: Sandy Bridge processor, QM67 PCH (Cougar Point), (Emerald Lake CRB, EVOC EC7-1817LNAR board)
+  + Intel Calpella Platform: Core i7 processor, QM57 PCH (Ibex Peak-M), (Red Fort CRB, Emerson MATXM CORE-411-B)
+  + Intel Nehalem/Westmere-EP Server: Xeon 56xx/55xx processors, 5520 chipset, ICH10R IOH (82801), (Hanlan Creek CRB)
+  + Intel Nehalem Workstation: Xeon 56xx/55xx processors, System SC5650SCWS (Greencity CRB)
+  + Intel Picket Post Server: Xeon 56xx/55xx processors (Jasper Forest), 3420 chipset (Ibex Peak), (Osage CRB)
+  + Intel Storage Platform: Sandy Bridge Xeon processor, C600 PCH (Patsburg), (Oak Creek Canyon CRB)
+  + Intel Shark Bay Client Platform: Haswell processor, LynxPoint PCH, (Walnut Canyon CRB, Lava Canyon CRB, Basking Ridge CRB, Flathead Creek CRB)
+  + Intel Shark Bay Ultrabook Platform: Haswell ULT processor, Lynx Point-LP PCH, (WhiteTip Mountain 1 CRB)
+
+Intel Atom platforms:
+  + Intel embedded Menlow: Intel Atom Z510/530 CPU, System Controller Hub US15W (Portwell NANO-8044)
+  + Intel Luna Pier: Intel Atom N4xx/D5xx series CPU (aka: Pineview-D & -M), 82801HM I/O Hub (ICH8M), (Advantech AIMB-212, Moon Creek CRB)
+  + Intel Queens Bay platform: Intel Atom E6xx CPU (aka: Tunnel Creek), Topcliff EG20T I/O Hub (Emerson NITX-315, Crown Bay CRB, Minnow Board)
+  + Intel Fish River Island platform: Intel Atom E6xx CPU (aka: Tunnel Creek), Topcliff EG20T I/O Hub (Kontron KM2M806)
+  + Intel Cedar Trail platform: Intel Atom N2000 & D2000 series CPU (aka: Cedarview), NM10 Express Chipset (Norco kit BIS-6630, Cedar Rock CRB)
+
+and is likely to work on many unlisted Atom/Core/Xeon based devices. The MACHINE
+type supports ethernet, wifi, sound, and Intel/vesa graphics by default in
+addition to common PC input devices, busses, and so on.  Note that it does not
+included the binary-only graphic drivers used on some Atom platforms, for
+accelerated graphics on these machines please refer to meta-intel.
+
+Depending on the device, it can boot from a traditional hard-disk, a USB device,
+or over the network. Writing 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 genericx86 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-genericx86.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 image to the USB-ZIP mode device:
+
+     # mkdir /tmp/image
+     # mkdir /tmp/usbkey
+     # mount -o loop core-image-minimal-genericx86.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 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 1000000 uImage-mpc8315e-rdb.bin
+ => tftp 2000000 uImage-mpc8315e-rdb.dtb
+ => bootm 1000000 - 2000000
+
+
+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.
+