README: Add build and boot instructions and restructure

The intel-common README in conf/machine/README doesn't describe how to
build an intel-common BSP, and with the removal of the
machine-specific BSPs, there's no longer any instructions at all for a
user to learn how to build and boot a meta-intel BSP.

This commit generalizes and adds those instructions back but this time
to the top-level README, which is also cleaned up and given a table of
contents to make it more useful.

It also moves the content from conf/machine/README to the top-level
README; conf/machine/README will be removed in another patch.

Signed-off-by: Tom Zanussi <tom.zanussi@linux.intel.com>
Signed-off-by: Saul Wold <sgw@linux.intel.com>

1 files changed, 299 insertions, 82 deletions

diff --git a/README b/README
index 63960c2e..d2098a9a 100644
--- a/README
+++ b/README
@@ -1,11 +1,62 @@
 meta-intel
 ==========
 
-This is the location for Intel maintained BSPs.
+This README file contains information on building and booting
+meta-intel BSP layers.  Please see the corresponding sections below
+for details.
 
-Please see the README files contained in the individual BSP layers for
-BSP-specific information. For details on the intel-common BSPs, see the
-conf/machine/README file.
+
+Yocto Project Compatible
+========================
+
+The BSPs contained in this layer are 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
+
+
+Table of Contents
+=================
+
+  I. Overview
+  II. Building and booting meta-intel BSP layers
+     a. Building the intel-common and quark BSP layers
+     b. Booting the intel-common BSP images
+     c. Booting the intel-quark BSP image on a Galileo board
+  III. Technical Miscellany
+     The intel-common kernel package architecture
+     Intel-specific machine features
+  IV. Tested Hardware
+  V.  Guidelines for submitting patches
+
+
+I. Overview
+===========
+
+This is the location for Intel-maintained BSPs.
+
+For details on the intel-common and intel-quark BSPs, see the
+information below.
+
+For all others, please see the README files contained in the
+individual BSP layers for BSP-specific information.
 
 If you have problems with or questions about a particular BSP, please
 contact the maintainer listed in the MAINTAINERS file directly (cc:ing
@@ -32,126 +83,211 @@ submit the bug against the most likely category for the problem - if
 you're wrong, it's not a big deal and the bug will be recategorized
 upon triage.
 
-Guidelines for submitting patches
-=================================
 
-Please submit any patches against meta-intel BSPs to the meta-intel
-mailing list (meta-intel@yoctoproject.org).  Also, if your patches are
-available via a public git repository, please also include a URL to
-the repo and branch containing your patches as that makes it easier
-for maintainers to grab and test your patches.
+II. Building and booting meta-intel BSP layers
+==============================================
 
-There are patch submission scripts available that will, among other
-things, automatically include the repo URL and branch as mentioned.
-Please see the Yocto Project Development Manual sections entitled
-'Using Scripts to Push a Change Upstream and Request a Pull' and
-'Using Email to Submit a Patch' for details.
+The following sections contain information on building and booting the
+BSPs contained in the meta-intel layer.
 
-Regardless of how you submit a patch or patchset, the patches should
-at minimum follow the suggestions outlined in the 'How to Submit a
-Change' secion in the Yocto Project Development Manual.  Specifically,
-they should:
+Note that these instructions specifically cover the intel-common and
+quark BSPs, which may or may not be applicable to other BSPs contained
+in this layer - if a given BSP contains its own README, that version
+should be used instead, and these instructions can be ignored.
 
-  - Include a 'Signed-off-by:' line.  A commit can't legally be pulled
-    in without this.
+a. Building the intel-common and quark BSP layers
+-------------------------------------------------
 
-  - Provide a single-line, short summary of the change.  This short
-    description should be prefixed by the BSP or recipe name, as
-    appropriate, followed by a colon.  Capitalize the first character
-    of the summary (following the colon).
+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 (or
+equivalently, check out the appropriate branch from the meta-intel git
+repository, see below).  For the intel-common and quark BSPs, those
+tarballs would correspond to the following choices in the BSP
+downloads section:
 
-  - For the body of the commit message, provide detailed information
-    that describes what you changed, why you made the change, and the
-    approach you used.
+ - Intel-core2-32 Intel® Common Core BSP (Intel-core2-32)
+ - Intel-core2-32 Intel® Common Core BSP (Intel-quark)
+ - Intel-corei7-64 Intel® Common Core BSP (Intel-corei7-64)
 
-  - If the change addresses a specific bug or issue that is associated
-    with a bug-tracking ID, include a reference to that ID in your
-    detailed description in the following format: [YOCTO #<bug-id>].
+The intel-* BSPs, also known as the intel-common BSPs, provide a few
+carefully selected tune options and generic hardware support to cover
+the majority of current Intel CPUs and devices. The naming follows the
+convention of intel-<TUNE>-<BITS>, where TUNE is the gcc cpu-type
+(used with mtune and march typically) and BITS is either 32 bit or 64
+bit.
 
-  - Pay attention to line length - please don't allow any particular
-    line in the commit message to stretch past 72 characters.
+Having done that, and assuming you extracted the BSP tarball contents
+at the top-level of your yocto build tree, you can build a BSP image
+by adding the location of the meta-intel layer to bblayers.conf e.g.:
 
-  - For any non-trivial patch, provide information about how you
-    tested the patch, and for any non-trivial or non-obvious testing
-    setup, provide details of that setup.
+  yocto/meta-intel \
 
-Doing a quick 'git log' in meta-intel will provide you with many
-examples of good example commits if you have questions about any
-aspect of the preferred format.
+To enable a particular machine, you need to add a MACHINE line naming
+the BSP to the local.conf file:
 
-The meta-intel maintainers will do their best to review and/or pull in
-a patch or patchset within 24 hours of the time it was posted.  For
-larger and/or more involved patches and patchsets, the review process
-may take longer.
+  MACHINE ?= "xxx"
 
+where 'xxx' is replaced by one of the following BSP names:
 
-Intel-specific machine features
-===============================
+ - intel-core2-32
 
-The meta-intel layer makes some additional machine features available
-to BSPs.  These machine features can be used in a BSP layer in the
-same way that machine features are used in other layers based on
-oe-core, via the MACHINE_FEATURES variable.
+   This BSP is optimized for the Core2 family of CPUs as well as all
+   Atom CPUs prior to the Silvermont core.
 
-Requirements
-------------
+ - intel-corei7-64
 
-The meta-intel-specific machine features are only available to a BSP
-when the meta-intel layer is included in the build configuration, and
-the meta-intel.inc file is included in the machine configuration of
-that BSP.
+   This BSP is optimized for Nehalem and later Core and Xeon CPUs as
+   well as Silvermont and later Atom CPUs, such as the Baytrail SoCs.
 
-To make these features available for your machine, you will need to:
+ - intel-quark
 
-  1. include a configuration line such as the below in bblayers.conf
-        BBLAYERS += "<local path>/meta-intel"
-  2. include the following line in the machine configuration file
-        require conf/machine/include/meta-intel.inc
+   This BSP is optimized for Quark-based systems.
 
-Once the above requirements are met, the machine features provided by
-the meta-intel layer will be available for the BSP to use.
+You should then be able to build an 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 intel-common BSP images').
+
+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.
+
+b. Booting the intel-common BSP images
+--------------------------------------
+
+If you downloaded the BSP tarball, you will find bootable images in
+the /binary directory.  If you've built your own image, either from
+the downloaded BSP layer or from the meta-intel git repository, you'll
+find the bootable image in the build/tmp/deploy/images/xxx directory,
+where again 'xxx' refers to the machine name used in the build.
 
-Building for Intel Quark X1000 microprocessor
----------------------------------------------
+The BSP /binary directory or build contains bootable live images,
+which can be used to directly boot Yocto off of a USB flash drive.
 
-To target the Intel Quark X1000. 
+Under Linux, insert a USB flash drive.  Assuming the USB flash drive
+takes device /dev/sdf, use dd to copy the live image to it.  For
+example:
+
+# dd if=core-image-sato-intel-corei7-64.hddimg of=/dev/sdf
+# sync
+# eject /dev/sdf
+
+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.
+
+If you find you're getting corrupt images on the USB (it doesn't show
+the syslinux boot: prompt, or the boot: prompt contains strange
+characters), try doing this first:
 
-  1. In conf/local.conf set the MACHINE type to be intel-quark.
+# dd if=/dev/zero of=/dev/sdf bs=1M count=512
 
-     MACHINE ??= "intel-quark"
+c. Booting the intel-quark BSP image on a Galileo board
+-------------------------------------------------------
 
-  2. Build a target image of your choice.
+If you downloaded the BSP tarball, you will find bootable images in
+the /binary directory.  If you've built your own image, either from
+the downloaded BSP layer or from the meta-intel git repository, you'll
+find the bootable image in the build/tmp/deploy/images/xxx directory,
+where again 'xxx' refers to the machine name used in the build.
 
-     $ bitbake core-image-minimal
+The Galileo board boots off of an SD card that has a special disk
+layout.  The 'wic' tool can be used to create an SD card adhering to
+that format via the following steps.
 
-  3. For the first time, you need to build parted-native too. (You will get an
-     error message when running wic script without it at later steps.)
+If you haven't already, you need to build parted-native. (You will get
+an error message when running the wic script if you haven't.)
 
-     $ bitbake parted-native
+    $ bitbake parted-native
 
-  4. Use the provided wic script to create an SD card image.
+Use the wic script to create an SD card image:
 
-     $ wic list images
+    $ wic list images
        mkgalileodisk                         Create an Galileo Gen 1/2 disk image
        mkgummidisk                           Create an EFI disk image
-       ...
+
+Assuming you want to boot the 'core-image-minimal' image:
 
      $ wic create mkgalileodisk -e core-image-minimal
 
-      wic script outputs the image and its location in success, something like:
-       ...
+If successful, the wic script generates the image and prints its location:
+
        Info: The new image(s) can be found here:
          /var/tmp/wic/build/mkgalileodisk-201604211444-mmcblk0.direct
        ...
 
-  5. Write the output image to an SD Card
+Write the output image to an SD Card
 
      $ sudo dd if=/path/to/image/mkgalileodisk-*-mmcblk0.direct of=/dev/your_sd_dev
  
-  6. Insert the SD Card into the reference platform and power on.
+Insert the SD Card into the reference platform and power on.
+
+
+III. Technical Miscellany
+=========================
+
+The intel-common kernel package architecture
+--------------------------------------------
+
+These BSPs use what we call the intel-common Linux kernel package
+architecture. This includes core2-32-intel-common and
+corei7-64-intel-common. These kernel packages can also be used by any
+of the BSPs in meta-intel that choose to include the
+intel-common-pkgarch.inc file.
+
+To minimize the proliferation of vendor trees, reduce the sources we
+must support, and consolidate QA efforts, all BSP maintainers are
+encouraged to make use of the intel-common Linux kernel package
+architecture.
+
+Intel-specific machine features
+-------------------------------
+
+The meta-intel layer makes some additional machine features available
+to BSPs.  These machine features can be used in a BSP layer in the
+same way that machine features are used in other layers based on
+oe-core, via the MACHINE_FEATURES variable.
+
+Requirements
+++++++++++++
+
+The meta-intel-specific machine features are only available to a BSP
+when the meta-intel layer is included in the build configuration, and
+the meta-intel.inc file is included in the machine configuration of
+that BSP.
+
+To make these features available for your machine, you will need to:
+
+  1. include a configuration line such as the below in bblayers.conf
+        BBLAYERS += "<local path>/meta-intel"
+  2. include the following line in the machine configuration file
+        require conf/machine/include/meta-intel.inc
+
+Once the above requirements are met, the machine features provided by
+the meta-intel layer will be available for the BSP to use.
 
 Available machine features
---------------------------
+++++++++++++++++++++++++++
 
 Currently, the meta-intel layer makes the following set of
 Intel-specific machine features available:
@@ -165,7 +301,7 @@ example:
         MACHINE_FEATURES += "intel-ucode"
 
 Machine feature details
------------------------
++++++++++++++++++++++++
 
  * intel-ucode
 
@@ -233,3 +369,84 @@ Machine feature details
        highly sensitive to target image size and which are not
        experiencing microcode-related issues might consider not
        enabling this feature.
+
+
+IV. Tested Hardware
+===================
+
+Of the BSPs currently included in meta-intel, the following have
+passed initial testing with the intel-common BSPs:
+
+intel-corei7-64:
+
+    crystalforest-server
+    crystalforest-gladden
+    haswell-wc
+    nuc (Ivy Bridge and Haswell, manual audio config required)
+    sugarbay
+
+intel-core2-32:
+
+    <currently under test>
+
+If you are interested in a BSP not listed here, chances are we are
+currently working on resolving some configuration issues with it.
+Please check the bugzilla and check in with us on the meta-intel
+mailing list.
+
+
+V. Guidelines for submitting patches
+====================================
+
+Please submit any patches against meta-intel BSPs to the meta-intel
+mailing list (meta-intel@yoctoproject.org).  Also, if your patches are
+available via a public git repository, please also include a URL to
+the repo and branch containing your patches as that makes it easier
+for maintainers to grab and test your patches.
+
+There are patch submission scripts available that will, among other
+things, automatically include the repo URL and branch as mentioned.
+Please see the Yocto Project Development Manual sections entitled
+'Using Scripts to Push a Change Upstream and Request a Pull' and
+'Using Email to Submit a Patch' for details.
+
+Regardless of how you submit a patch or patchset, the patches should
+at minimum follow the suggestions outlined in the 'How to Submit a
+Change' secion in the Yocto Project Development Manual.  Specifically,
+they should:
+
+  - Include a 'Signed-off-by:' line.  A commit can't legally be pulled
+    in without this.
+
+  - Provide a single-line, short summary of the change.  This short
+    description should be prefixed by the BSP or recipe name, as
+    appropriate, followed by a colon.  Capitalize the first character
+    of the summary (following the colon).
+
+  - For the body of the commit message, provide detailed information
+    that describes what you changed, why you made the change, and the
+    approach you used.
+
+  - If the change addresses a specific bug or issue that is associated
+    with a bug-tracking ID, include a reference to that ID in your
+    detailed description in the following format: [YOCTO #<bug-id>].
+
+  - Pay attention to line length - please don't allow any particular
+    line in the commit message to stretch past 72 characters.
+
+  - For any non-trivial patch, provide information about how you
+    tested the patch, and for any non-trivial or non-obvious testing
+    setup, provide details of that setup.
+
+Doing a quick 'git log' in meta-intel will provide you with many
+examples of good example commits if you have questions about any
+aspect of the preferred format.
+
+The meta-intel maintainers will do their best to review and/or pull in
+a patch or patchset within 24 hours of the time it was posted.  For
+larger and/or more involved patches and patchsets, the review process
+may take longer.
+
+Please see the meta-intel/MAINTAINERS file for the list of maintainers
+and their specific areas; it's also a good idea to cc: the specific
+maintainer, if applicable.