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

Overview of Intel Communication Product Offering
------------------------------------------------

The following platforms are supported on meta-intel dizzy branch ONLY:

Crystal Forest/Server - Shumway reference platform configurations:
processor: Intel Xeon E5-2600/E5-2400       (Sandy Bridge-based) or
           Intel Xeon E5-2600v2/E5-2400v2   (Ivy Bridge-based)
chipset:   Intel Communication Chipset 8900-8920 Series (Cave Creek)
url: http://www.intel.com/p/en_US/embedded/hwsw/hardware/xeon-e5-89xx/overview

Crystal Forest/Gladden - Stargo reference platform configurations:
processor: Intel Xeon E3-1125C/E3-1105C     (Sandy Bridge-based) or
           Intel Xeon E3-1125v2/E3-1105v2   (Ivy Bridge-based)
chipset:   Intel Communication Chipset 8900-8920 Series (Cave Creek)
url: http://www.intel.com/p/en_US/embedded/hwsw/hardware/xeon-core-pentium-celeron-89xx/overview

Highland Forest (Crystal Forest/Server Refresh) - Shumway reference platform configurations:
processor: Intel Xeon E5-2600v2/E5-2400v2   (Ivy Bridge-based)
chipset:   Intel Communication Chipset 8925-8955 Series (Coleto Creek)
url: https://www-ssl.intel.com/content/www/us/en/intelligent-systems/crystal-forest-server/xeon-e5-v2-89xx-chipset-ibd.html

The following platform is supported on meta-intel fido branch and beyond.

River Forest - Long Brook reference platform configurations:
processor: Intel Xeon E5-2600v3/E5-2400v3   (Haswell EP-based)
chipset:   Intel Communication Chipset 8925-8955 Series (Coleto Creek)
url: https://www-ssl.intel.com/content/www/my/en/embedded/products/river-forest/overview.html?wapkw=coleto

All above four platforms use PCIe-based Matrox graphics card for display.

More 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 mailing
list (meta-intel@yoctoproject.org) and cc: the maintainer:

Maintainer: Wu Chia Chuan <chia.chuan.wu@intel.com>

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


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

  I. Building the meta-crystalforest BSP layer
 II. Booting the images in /binary
III. Device Notes
    a. Boot Loader
    b. I/O drivers
IV. Enabling Intel DPDK and QuickAssist Technology

I. Building the meta-crystalforest 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 done that, and assuming you extracted the BSP tarball contents
at the top-level of your yocto build tree, you can build a crystalforest
image by adding the location of the meta-crystalforest 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-crystalforest \

Crystal Forest layer is meant for building both Crystal Forest Gladden
and Crystal Forest Server platforms. By enabling Crystal Forest layer,
the image you build is able to boot on both supported platforms.

To enable the Crystal Forest layer, add the Crystal Forest MACHINE to
build/local.conf:

  MACHINE ?= "crystalforest"

You should then be able to build a crystalforest 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').

The live image is located within build/tmp/deploy/images/<machine> folder.

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 bootable live images, which can be used to directly
boot Yocto off of a USB flash drive.

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-<machine>.hddimg /dev/sda

Follow the prompts on the screen to confirm the action.

This should give you a bootable USB flash device.  Insert the device
into a bootable USB socket on the target, and power on.  This should
result in a system booted to the Sato graphical desktop.

If you want a terminal, use the arrows at the top of the UI to move to
different pages of available applications, one of which is named
'Terminal'.  Clicking that should give you a root terminal.

If you want to ssh into the system, you can use the root terminal to
ifconfig the IP address and use that to ssh in.  The root password is
empty, so to log in type 'root' for the user name and hit 'Enter' at
the Password prompt: and you should be in.

III. Device Notes
=================

a. Boot Loader
--------------
- Support BIOS version at Shumway board (HighlandForest/CrystalForest-server):
   CCFRCLC0.019

- Support BIOS version at Stargo board ( CrystalForest-Gladden ):
  CIVGCCK1.86C.0003.P00

- Support BIOS version at Long Brook board (RiverForest)
  GRNDCRB1.86B.0022.R01.i02.1405151000

b. I/O drivers
--------------
-Support Matrox graphic card.
-Support SATA, USB Host v2.0
-Supported I/O devices (APIC, RTC, SPI, UART, I2C, LPS, SMBus i801,
 WDT, and HPET)


IV. Enabling Intel DPDK and QuickAssist Technology
===================================================

DPDK recipe: meta-intel/meta-isg/common/recipes-extended/dpdk
QAT recipe:  meta-intel/meta-isg/common/recipes-extended/qat
QAT-enable zlib recipe: meta-intel/meta-isg/common/recipes-extended/zlib-qat

Note:
qat16 recipe is meant for platform with Coleto Creek  chipset.
qat15 recipe is meant for platform with Cave Creek chipset.

conf/machine/crystalforest.conf is the common machine configuration
to support Crystal Forest/server, Crystal Forest/gladden, Highland Forest and
River Forest. In order to generate the right binary for these platforms which
have different QAT technology, user could change the default config accordingly
within crystalforest.conf as below:

For Coleto Creek chipset:
PREFERRED_PROVIDER_virtual/qat ?= "qat16"

For Cave Creek chipset:
PREFERRED_PROVIDER_virtual/qat ?= "qat15"

Another option and preferred approach for above setting is to override
configuration under build/conf/local.conf as follow:

For Coleto Creek chipset:
PREFERRED_PROVIDER_virtual/qat = "qat16"

For Cave Creek chipset:
PREFERRED_PROVIDER_virtual/qat = "qat15"

By default, the machine configuration does not assume that the above
ingredients are pre-installed onto the BSP. Developers are required
to either use smart tool to install those software packages or
configure IMAGE_INSTALL under build/conf/local.conf, for example.

For Coleto Creek chipset:
IMAGE_INSTALL += "dpdk qat16 zlib-qat"

For Cavecreek Creek chipset:
IMAGE_INSTALL += "dpdk qat15 zlib-qat"

The list of packages can be searched under tmp/deploy/<package-type>
folder.
