yocto-poky/README.hardware - mdmillerii/openbmc - Gitiles

                           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 Beaglebone (beaglebone)
   * Freescale MPC8315E-RDB (mpc8315e-rdb)

 For more information see the board's section below. The appropriate MACHINE
 variable value corresponding to the board is given in brackets.

 Reference Board Maintenance
 ===========================

 Send pull requests, patches, comments or questions about meta-yocto-bsps to poky@yoctoproject.org

 Maintainers: Kevin Hao <kexin.hao@windriver.com>
              Bruce Ashfield <bruce.ashfield@windriver.com>

 Consumer Devices
 ================

 The following consumer devices are supported by the meta-yocto-bsp layer:

   * Intel x86 based PCs and devices (genericx86)
   * Ubiquiti Networks EdgeRouter Lite (edgerouter)

 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.

 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 Beaglebone (beaglebone)
 =========================================

 The Beaglebone is an ARM Cortex-A8 development board with USB, Ethernet, 2D/3D
 accelerated graphics, audio, serial, JTAG, and SD/MMC. The Black adds a faster
 CPU, more RAM, eMMC flash and a micro HDMI port. The beaglebone MACHINE is
 tested on the following platforms:

   o Beaglebone Black A6
   o Beaglebone A6 (the original "White" model)

 The Beaglebone Black has eMMC, while the White does not. Pressing the USER/BOOT
 button when powering on will temporarily change the boot order. But for the sake
 of simplicity, these instructions assume you have erased the eMMC on the Black,
 so its boot behavior matches that of the White and boots off of SD card. To do
 this, issue the following commands from the u-boot prompt:

     # mmc dev 1
     # mmc erase 0 512

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

 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 partitions 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-beaglebone /media/boot/MLO
      # cp u-boot-beaglebone.img /media/boot/u-boot.img

   3. Install the root filesystem
      # tar x -C /media/root -f core-image-$IMAGE_TYPE-beaglebone.tar.bz2

   4. If using core-image-base or core-image-sato images, the SD card is ready
      and rootfs already contains the kernel, modules and device tree (DTB)
      files necessary to be booted with U-boot's default configuration, so
      skip directly to step 8.
      For core-image-minimal, proceed through next steps.

   5. If using core-image-minimal rootfs, install the modules
      # tar x -C /media/root -f modules-beaglebone.tgz

   6. If using core-image-minimal rootfs, install the kernel zImage into /boot
      directory of rootfs
      # cp zImage-beaglebone.bin /media/root/boot/zImage

   7. If using core-image-minimal rootfs, also install device tree (DTB) files
      into /boot directory of rootfs
      # cp zImage-am335x-bone.dtb /media/root/boot/am335x-bone.dtb
      # cp zImage-am335x-boneblack.dtb /media/root/boot/am335x-boneblack.dtb

   8. Unmount the SD partitions, insert the SD card into the Beaglebone, and
      boot the Beaglebone


 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

 --- Booting from JFFS2 root ---

  1. First boot the board with NFS root.

  2. Erase the MTD partition which will be used as root:

     $ flash_eraseall  /dev/mtd3

  3. Copy the JFFS2 image to the MTD partition:

     $ flashcp core-image-minimal-mpc8315e-rdb.jffs2 /dev/mtd3

  4. Then reboot the board and set up the environment in U-Boot:

     => setenv bootargs root=/dev/mtdblock3 rootfstype=jffs2 console=ttyS0,115200


 Ubiquiti Networks EdgeRouter Lite (edgerouter)
 ==============================================

 The EdgeRouter Lite is part of the EdgeMax series. It is a MIPS64 router
 (based on the Cavium Octeon processor) with 512MB of RAM, which uses an
 internal USB pendrive for storage.

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

 You will need the following:
 * RJ45 -> serial ("rollover") cable connected from your PC to the CONSOLE
   port on the device
 * Ethernet connected to the first ethernet port on the board

 If using NFS as part of the setup process, you will also need:
 * NFS root setup on your workstation
 * TFTP server installed on your workstation (if fetching the kernel from
   TFTP, see below).

 --- Preparation ---

 Build an image (e.g. core-image-minimal) using "edgerouter" as the MACHINE.
 In the following instruction it is based on core-image-minimal. Another target
 may be similiar with it.

 --- Booting from NFS root / kernel via TFTP ---

 Load the kernel, and boot the system as follows:

  1. Get the kernel (vmlinux) file from the tmp/deploy/images/edgerouter
     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/ttyS0 -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>

  5. Download the kernel and boot:

  => tftp tftp $loadaddr vmlinux
  => bootoctlinux $loadaddr coremask=0x3 root=/dev/nfs rw nfsroot=<nfsroot ip>:<rootfs path> ip=<board ip>:<server ip>:<gateway ip>:<netmask>:edgerouter:eth0:off mtdparts=phys_mapped_flash:512k(boot0),512k(boot1),64k@3072k(eeprom)

 --- Booting from USB root ---

 To boot from the USB disk, you either need to remove it from the edgerouter
 box and populate it from another computer, or use a previously booted NFS
 image and populate from the edgerouter itself.

 Type 1: Mounted USB disk
 ------------------------

 To boot from the USB disk there are two available partitions on the factory
 USB storage. The rest of this guide assumes that these partitions are left
 intact. If you change the partition scheme, you must update your boot method
 appropriately.

 The standard partitions are:

   - 1: vfat partition containing factory kernels
   - 2: ext3 partition for the root filesystem.

 You can place the kernel on either partition 1, or partition 2, but the roofs
 must go on partition 2 (due to its size).

 Note: If you place the kernel on the ext3 partition, you must re-create the
       ext3 filesystem, since the factory u-boot can only handle 128 byte inodes and
       cannot read the partition otherwise.

 Steps:

  1. Remove the USB disk from the edgerouter and insert it into a computer
     that has access to your build artifacts.

  2. Copy the kernel image to the USB storage (assuming discovered as 'sdb' on
     the development machine):

     2a) if booting from vfat

         # mount /dev/sdb1 /mnt
         # cp tmp/deploy/images/edgerouter/vmlinux /mnt
         # umount /mnt

     2b) if booting from ext3

         # mkfs.ext3 -I 128 /dev/sdb2
         # mount /dev/sdb2 /mnt
         # mkdir /mnt/boot
         # cp tmp/deploy/images/edgerouter/vmlinux /mnt/boot
         # umount /mnt

  3. Extract the rootfs to the USB storage ext3 partition

         # mount /dev/sdb2 /mnt
         # tar -xvjpf core-image-minimal-XXX.tar.bz2 -C /mnt
         # umount /mnt

  4. Reboot the board and press a key on the terminal when prompted to get to the U-Boot
     command line:

  5. Load the kernel and boot:

     5a) vfat boot

          => fatload usb 0:1 $loadaddr vmlinux

     5b) ext3 boot

          => ext2load usb 0:2 $loadaddr boot/vmlinux

     => bootoctlinux $loadaddr coremask=0x3 root=/dev/sda2 rw rootwait mtdparts=phys_mapped_flash:512k(boot0),512k(boot1),64k@3072k(eeprom)


 Type 2: NFS
 -----------

 Note: If you place the kernel on the ext3 partition, you must re-create the
       ext3 filesystem, since the factory u-boot can only handle 128 byte inodes and
       cannot read the partition otherwise.

       These boot instructions assume that you have recreated the ext3 filesystem with
       128 byte inodes, you have an updated uboot or you are running and image capable
       of making the filesystem on the board itself.


  1. Boot from NFS root

  2. Mount the USB disk partition 2 and then extract the contents of
     tmp/deploy/core-image-XXXX.tar.bz2 into it.

     Before starting, copy core-image-minimal-xxx.tar.bz2 and vmlinux into
     rootfs path on your workstation.

     and then,

       # mount /dev/sda2 /media/sda2
       # tar -xvjpf core-image-minimal-XXX.tar.bz2 -C /media/sda2
       # cp vmlinux /media/sda2/boot/vmlinux
       # umount /media/sda2
       # reboot

  3. Reboot the board and press a key on the terminal when prompted to get to the U-Boot
     command line:

     # reboot

  4. Load the kernel and boot:

       => ext2load usb 0:2 $loadaddr boot/vmlinux
       => bootoctlinux $loadaddr coremask=0x3 root=/dev/sda2 rw rootwait mtdparts=phys_mapped_flash:512k(boot0),512k(boot1),64k@3072k(eeprom)
	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 Beaglebone (beaglebone)
	* Freescale MPC8315E-RDB (mpc8315e-rdb)

	For more information see the board's section below. The appropriate MACHINE
	variable value corresponding to the board is given in brackets.

	Reference Board Maintenance
	===========================

	Send pull requests, patches, comments or questions about meta-yocto-bsps to poky@yoctoproject.org

	Maintainers: Kevin Hao <kexin.hao@windriver.com>
	Bruce Ashfield <bruce.ashfield@windriver.com>

	Consumer Devices
	================

	The following consumer devices are supported by the meta-yocto-bsp layer:

	* Intel x86 based PCs and devices (genericx86)
	* Ubiquiti Networks EdgeRouter Lite (edgerouter)

	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.

	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 Beaglebone (beaglebone)
	=========================================

	The Beaglebone is an ARM Cortex-A8 development board with USB, Ethernet, 2D/3D
	accelerated graphics, audio, serial, JTAG, and SD/MMC. The Black adds a faster
	CPU, more RAM, eMMC flash and a micro HDMI port. The beaglebone MACHINE is
	tested on the following platforms:

	o Beaglebone Black A6
	o Beaglebone A6 (the original "White" model)

	The Beaglebone Black has eMMC, while the White does not. Pressing the USER/BOOT
	button when powering on will temporarily change the boot order. But for the sake
	of simplicity, these instructions assume you have erased the eMMC on the Black,
	so its boot behavior matches that of the White and boots off of SD card. To do
	this, issue the following commands from the u-boot prompt:

	# mmc dev 1
	# mmc erase 0 512

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

	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 partitions 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-beaglebone /media/boot/MLO
	# cp u-boot-beaglebone.img /media/boot/u-boot.img

	3. Install the root filesystem
	# tar x -C /media/root -f core-image-$IMAGE_TYPE-beaglebone.tar.bz2

	4. If using core-image-base or core-image-sato images, the SD card is ready
	and rootfs already contains the kernel, modules and device tree (DTB)
	files necessary to be booted with U-boot's default configuration, so
	skip directly to step 8.
	For core-image-minimal, proceed through next steps.

	5. If using core-image-minimal rootfs, install the modules
	# tar x -C /media/root -f modules-beaglebone.tgz

	6. If using core-image-minimal rootfs, install the kernel zImage into /boot
	directory of rootfs
	# cp zImage-beaglebone.bin /media/root/boot/zImage

	7. If using core-image-minimal rootfs, also install device tree (DTB) files
	into /boot directory of rootfs
	# cp zImage-am335x-bone.dtb /media/root/boot/am335x-bone.dtb
	# cp zImage-am335x-boneblack.dtb /media/root/boot/am335x-boneblack.dtb

	8. Unmount the SD partitions, insert the SD card into the Beaglebone, and
	boot the Beaglebone


	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

	--- Booting from JFFS2 root ---

	1. First boot the board with NFS root.

	2. Erase the MTD partition which will be used as root:

	$ flash_eraseall /dev/mtd3

	3. Copy the JFFS2 image to the MTD partition:

	$ flashcp core-image-minimal-mpc8315e-rdb.jffs2 /dev/mtd3

	4. Then reboot the board and set up the environment in U-Boot:

	=> setenv bootargs root=/dev/mtdblock3 rootfstype=jffs2 console=ttyS0,115200


	Ubiquiti Networks EdgeRouter Lite (edgerouter)
	==============================================

	The EdgeRouter Lite is part of the EdgeMax series. It is a MIPS64 router
	(based on the Cavium Octeon processor) with 512MB of RAM, which uses an
	internal USB pendrive for storage.

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

	You will need the following:
	* RJ45 -> serial ("rollover") cable connected from your PC to the CONSOLE
	port on the device
	* Ethernet connected to the first ethernet port on the board

	If using NFS as part of the setup process, you will also need:
	* NFS root setup on your workstation
	* TFTP server installed on your workstation (if fetching the kernel from
	TFTP, see below).

	--- Preparation ---

	Build an image (e.g. core-image-minimal) using "edgerouter" as the MACHINE.
	In the following instruction it is based on core-image-minimal. Another target
	may be similiar with it.

	--- Booting from NFS root / kernel via TFTP ---

	Load the kernel, and boot the system as follows:

	1. Get the kernel (vmlinux) file from the tmp/deploy/images/edgerouter
	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/ttyS0 -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>

	5. Download the kernel and boot:

	=> tftp tftp $loadaddr vmlinux
	=> bootoctlinux $loadaddr coremask=0x3 root=/dev/nfs rw nfsroot=<nfsroot ip>:<rootfs path> ip=<board ip>:<server ip>:<gateway ip>:<netmask>:edgerouter:eth0:off mtdparts=phys_mapped_flash:512k(boot0),512k(boot1),64k@3072k(eeprom)

	--- Booting from USB root ---

	To boot from the USB disk, you either need to remove it from the edgerouter
	box and populate it from another computer, or use a previously booted NFS
	image and populate from the edgerouter itself.

	Type 1: Mounted USB disk
	------------------------

	To boot from the USB disk there are two available partitions on the factory
	USB storage. The rest of this guide assumes that these partitions are left
	intact. If you change the partition scheme, you must update your boot method
	appropriately.

	The standard partitions are:

	- 1: vfat partition containing factory kernels
	- 2: ext3 partition for the root filesystem.

	You can place the kernel on either partition 1, or partition 2, but the roofs
	must go on partition 2 (due to its size).

	Note: If you place the kernel on the ext3 partition, you must re-create the
	ext3 filesystem, since the factory u-boot can only handle 128 byte inodes and
	cannot read the partition otherwise.

	Steps:

	1. Remove the USB disk from the edgerouter and insert it into a computer
	that has access to your build artifacts.

	2. Copy the kernel image to the USB storage (assuming discovered as 'sdb' on
	the development machine):

	2a) if booting from vfat

	# mount /dev/sdb1 /mnt
	# cp tmp/deploy/images/edgerouter/vmlinux /mnt
	# umount /mnt

	2b) if booting from ext3

	# mkfs.ext3 -I 128 /dev/sdb2
	# mount /dev/sdb2 /mnt
	# mkdir /mnt/boot
	# cp tmp/deploy/images/edgerouter/vmlinux /mnt/boot
	# umount /mnt

	3. Extract the rootfs to the USB storage ext3 partition

	# mount /dev/sdb2 /mnt
	# tar -xvjpf core-image-minimal-XXX.tar.bz2 -C /mnt
	# umount /mnt

	4. Reboot the board and press a key on the terminal when prompted to get to the U-Boot
	command line:

	5. Load the kernel and boot:

	5a) vfat boot

	=> fatload usb 0:1 $loadaddr vmlinux

	5b) ext3 boot

	=> ext2load usb 0:2 $loadaddr boot/vmlinux

	=> bootoctlinux $loadaddr coremask=0x3 root=/dev/sda2 rw rootwait mtdparts=phys_mapped_flash:512k(boot0),512k(boot1),64k@3072k(eeprom)


	Type 2: NFS
	-----------

	Note: If you place the kernel on the ext3 partition, you must re-create the
	ext3 filesystem, since the factory u-boot can only handle 128 byte inodes and
	cannot read the partition otherwise.

	These boot instructions assume that you have recreated the ext3 filesystem with
	128 byte inodes, you have an updated uboot or you are running and image capable
	of making the filesystem on the board itself.


	1. Boot from NFS root

	2. Mount the USB disk partition 2 and then extract the contents of
	tmp/deploy/core-image-XXXX.tar.bz2 into it.

	Before starting, copy core-image-minimal-xxx.tar.bz2 and vmlinux into
	rootfs path on your workstation.

	and then,

	# mount /dev/sda2 /media/sda2
	# tar -xvjpf core-image-minimal-XXX.tar.bz2 -C /media/sda2
	# cp vmlinux /media/sda2/boot/vmlinux
	# umount /media/sda2
	# reboot

	3. Reboot the board and press a key on the terminal when prompted to get to the U-Boot
	command line:

	# reboot

	4. Load the kernel and boot:

	=> ext2load usb 0:2 $loadaddr boot/vmlinux
	=> bootoctlinux $loadaddr coremask=0x3 root=/dev/sda2 rw rootwait mtdparts=phys_mapped_flash:512k(boot0),512k(boot1),64k@3072k(eeprom)