This README file contains information on building the meta-valleyisland
BSP layer, and booting the images contained in the /binary directory.
Please see the corresponding sections below for details.

The Valley Island BSP consists of two versions:
1. 32-bit Valley Island
2. 64-bit Valley Island

The BSP is made specifically for Intel® Atom E3800 Processor
Development Kit (formerly known as Valley Island). This BSP integrates
Intel Graphics for Linux driver (i965) as the integrated graphics.

Valley Island BSP is meant to support the following platforms:
1. Valley Island Development Kit
2. Bayley Bay CRB
3. Bakersport CRB
4. MinnowBoard MAX

Further information on the platforms supported by this BSP can be
found here:

  http://www.intel.com/content/www/us/en/intelligent-systems/bay-trail/atom-processor-e3800-family-overview.html

Information on all Intel® embedded platforms can be found here:

  http://www.intel.com/p/en_US/embedded/hwsw/hardware

Yocto Project Compatible
========================

This BSP is compatible with the Yocto Project as per the requirements
listed here:

  https://www.yoctoproject.org/webform/yocto-project-compatible-registration

Dependencies
============

This layer depends on:

  URI: git://git.openembedded.org/bitbake
  branch: master

  URI: git://git.openembedded.org/openembedded-core
  layers: meta
  branch: master

  URI: git://git.yoctoproject.org/meta-intel
  layers: intel
  branch: master

Patches
=======

Please submit any patches against this BSP to the Meta-Intel Yocto mailing list
(meta-intel@yoctoproject.org) and cc: the maintainer:

Maintainer: Chang Rebecca Swee Fun <rebecca.swee.fun.chang@intel.com>

Please see the meta-isg/MAINTAINERS file for more details.

Table of Contents
=================

  I. Building the meta-valleyisland BSP layer
 II. Booting the images in /binary
III. Device Notes
     a. Boot Loader
     b. I/O drivers
     c. LPIO ACPI enumeration support
 IV. Known Issues
     a. I/O drivers


I. Building the meta-valleyisland BSP layer
===========================================

In order to build an image with BSP support for a given release, you
need to download the corresponding BSP tarball from the 'Board Support
Package (BSP) Downloads' page of the Yocto Project website.

Having that done, and assuming you have extracted the BSP tarball contents
at the top-level of your Yocto build tree, you can build a valleyisland
image by adding the location of the meta-valleyisland layer to
bblayers.conf, along with the meta-intel layer itself (to access
common metadata shared between BSPs) e.g.:

  yocto/meta-intel \
  yocto/meta-intel/meta-isg/meta-valleyisland \

To enable the 32-bit Valley Island layer, add the valleyisland-32 MACHINE to local.conf:

  MACHINE ?= "valleyisland-32"

To enable the 64-bit Valley Island layer, add the valleyisland-64 MACHINE to local.conf:

  MACHINE ?= "valleyisland-64"

The meta-valleyisland contains support for Intel HD Audio. However, HD Audio
driver is dependent on gstreamer plugins and ffmpeg plugins to work properly.
These gstreamer plugins require license flags in order to be included in the build.

Add "commercial" in the LICENSE_FLAGS_WHITELIST in local.conf. For example:

  LICENSE_FLAGS_WHITELIST = "commercial"

The meta-valleyisland contains support for Marvell 8897 Wireless/Bluetooth
card. This require dependencies of meta-openembedded layer and add the layer
dependencies to the BBLAYERS variable in order to build the BSP as below:
$ git clone -b dizzy git://git.openembedded.org/meta-openembedded

In bblayers.conf: Add BBLAYERS ?= "/path/meta-openembedded/meta-oe \"

To support Marvell 8897 module in AP mode and STA mode, add "hostapd iw
dhcp-client dhcp-server" in the CORE_IMAGE_EXTRA_INSTALL in local.conf. For
example:
CORE_IMAGE_EXTRA_INSTALL = "hostapd iw dhcp-client dhcp-server"

You should then be able to build a valleyisland image as such:

  $ source oe-init-build-env
  $ bitbake core-image-sato

At the end of a successful build, you should have a live image that
you can boot from a USB flash drive (see instructions on how to do
that below, in the section 'Booting the images from /binary').

As an alternative to downloading the BSP tarball, you can also work
directly from the meta-intel git repository.  For each BSP in the
'meta-intel' repository, there are multiple branches, one
corresponding to each major release starting with 'laverne' (0.90), in
addition to the latest code which tracks the current master (note that
not all BSPs are present in every release).  Instead of extracting a
BSP tarball at the top level of your yocto build tree, you can
equivalently check out the appropriate branch from the meta-intel
repository at the same location.

II. Booting the images in /binary
=================================

This BSP contains (or builds) live images which must be converted to a
partitioned image format in order to boot them on the Valley Island
Development Kit, Bayley Bay CRB and Bakersport CRB.

You can deploy the hddimg image to a USB or SATA device. You will
need to know the device name on your host as well as the device name on
the target. Be careful with this step as using the wrong host device can
result in overwriting data on your host machine.

Under Linux, USB and SATA devices typically appears as /dev/sdb,
/dev/sdc, etc. Watching your system messages as you connect the device
will tell you exactly which device name is assigned to the device.
On the Valley Island platform, assuming only one storage device is
attached at boot, a USB or SATA device will be /dev/sda.

After inserting the boot media into your host machine and determining
your host and target device, create the image using the mkefidisk.sh
script, provided by poky under scripts/contrib/. Note that root
privileges are required. For example, using an USB device which appears
as /dev/sdc on the host:

$ sudo ./mkefidisk.sh /dev/sdc core-image-sato-valleyisland-32.hddimg /dev/sda

Follow the prompts on the screen to confirm the action.

Insert the device into the Valley Island platform and power on. This
should result in a system booted to the Sato graphical desktop.

The root password is empty on the Poky reference distribution images.


III. Device Notes
=================
a. Boot Loader
--------------
Valley Island Development Kit
BIOS : EBC MF01X003
Note : It is recommended to use the default settings of this BIOS version.

Bayley Bay/ Bakersport CRB/ MinnowBoard MAX
BIOS : ISG BIOS 093_041
EC   : KSC v3.14

Required settings in ISG BIOS

  OS Selection:
    Device Manager -> Boot -> OS Selection -> Yocto Linux

  Turn off Secure-boot:
    Device Manager -> Secure Boot Configuration -> Attempt Secure Boot ->
    Uncheck

  Turn off LPE Audio Support:
    Device Manager -> System Setup -> South Cluster Configuration ->
    Audio Configuration -> LPE Audio Support -> Disable

  Turn on HD Audio Support:
    Device Manager -> System Setup -> South Cluster Configuration ->
    Audio Configuration -> Azalia Controller -> Enable

Please use EFI mode for all boot medium types, i.e. USB disk and Hard Disk.
Setting in BIOS:

  Choose boot medium:
    Boot Manager -> EFI (Hard Drive/USB Device)

  Save settings:
    Boot Maintenance Manager -> Boot Options -> Change Boot Order ->
    Change the order -> Commmit Changes and Exit


b. I/O drivers
--------------
The I2C controller driver supports fast mode by default.
To enable standard mode, appends the arguments to kernel command line.

  "i2c-designware-pci.force_std_mode=1" (PCI mode)
  "i2c-designware-platform.force_std_mode=1" (ACPI mode)


c. LPIO ACPI enumeration support
--------------------------------
Required settings in ISG BIOS

  Turn on ACPI mode
    Device Manager -> System Setup -> South Cluster Configuration ->
    LPSS & SCC Configuration -> LPSS & SCC Device Mode -> ACPI mode

Some LPSS devices are hidden in ACPI mode to support Windows. To enable
these devices, toggle the following in the BIOS Menu.

  Device Manager -> System Setup -> South Cluster Configuration -> Miscellaneous
  Configuration -> Unsupported LPSS Device and select "Unhide"


IV. Known Limitations
=====================
a. I/O drivers
--------------
HSUART:

When runninig PCI mode HSUART at baud rate 2M and above, you may observe
kernel message "serial8250: too much work for irq...". Most of the time it
won't disrupt the transfer and able to complete without data corruption.
However, occasionally your transfer may halt when that kernel message appear.
In this case, you would need to re-open the HSUART port.
