README.hardware

                          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 and genericx86-64 MACHINE are tested on the following platforms:

Intel Xeon/Core i-Series:
  + Intel NUC5 Series - ix-52xx Series SOC (Broadwell)
  + Intel NUC6 Series - ix-62xx Series SOC (Skylake)
  + Intel Shumway Xeon Server

Intel Atom platforms:
  + MinnowBoard MAX - E3825 SOC (Bay Trail)
  + MinnowBoard MAX - Turbot (ADI Engineering) - E3826 SOC (Bay Trail)
    - These boards can be either 32bot or 64bit modes depending on firmware
    - See minnowboard.org for details 
  + Intel Braswell SOC

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. Use a ".wic" image with an EFI partition

     a) With a default grub-efi bootloader:
     # dd if=core-image-minimal-genericx86-64.wic of=/dev/sdb

     b) Use systemd-boot instead
     - Build an image with EFI_PROVIDER="systemd-boot" then use the above
       dd command to write the image to a USB stick.


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:

  1. Build an image. For example:

     $ bitbake core-image-minimal

  2. Use the "dd" utility to write the image to the SD card. For example:

     # dd core-image-minimal-beaglebone.wic of=/dev/sdb

  3. Insert the SD card into the Beaglebone and boot the board.

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.

Note: To boot from USB disk you need u-boot that supports 'ext2load usb'
command. You need to setup TFTP server, load u-boot from there and
flash it to NOR flash.

Beware! Flashing bootloader is potentially dangerous operation that can
brick your device if done incorrectly. Please, make sure you understand
what below commands mean before executing them.

Load the new u-boot.bin from TFTP server to memory address 200000
=> tftp 200000 u-boot.bin

Disable flash protection
=> protect off all

Erase the old u-boot from fe000000 to fe06ffff in NOR flash.
The size is 0x70000 (458752 bytes)
=> erase fe000000 fe06ffff

Copy the new u-boot from address 200000 to fe000000
the size is 0x70000. It has to be greater or equal to u-boot.bin size
=> cp.b 200000 fe000000 70000

Enable flash protection again
=> protect on all

Reset the board
=> reset

--- Booting from USB disk ---

 1. Flash partitioned image to the USB disk

    # dd if=core-image-minimal-mpc8315e-rdb.wic of=/dev/sdb

 2. Plug USB disk into the MPC8315 board

 3. 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

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

 5. Optional. Load the u-boot.bin from the USB disk:

 => usb start
 => ext2load usb 0:1 200000 u-boot.bin

    and flash it to NOR flash as described above.

 6. Set fdtaddr and loadaddr. This is not necessary if you set them before.

 => setenv fdtaddr a00000
 => setenv loadaddr 1000000

 7. Load the kernel and dtb from first partition of the USB disk:

 => usb start
 => ext2load usb 0:1 $loadaddr uImage
 => ext2load usb 0:1 $fdtaddr dtb

 8. Set bootargs and boot up the device

 => setenv bootargs root=/dev/sdb2 rw rootwait console=ttyS0,115200
 => bootm $loadaddr - $fdtaddr


--- 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 disk ---

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: Use partitioned image
-----------------------------

Steps:

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

 2. Flash the image.

    # dd if=core-image-minimal-edgerouter.wic of=/dev/sdb

 3. Insert USB disk into the edgerouter and boot it.

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)